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Preface 


Manual Objectives 


The purpose of this manual is to familiarize the users of the IAS operating systems with the File 
Control Services (FCS) facility provided with the system. 


Intended Audience 


Because the File Control Services described in this manual pertain to both MACRO-11 and 
FORTRAN programs, the reader is assumed to be familiar with these languages. Also, because the 
development of programs in an IAS environment requires the use of the Task Builder (TKB), the 
reader should be familiar with the contents of the JAS Task Builder Manual. 


Document Structure 


Chapter 1 describes the FCS features available for IAS users. It also defines some of the 
terminology used throughout the manual. This chapter is important to understanding the balance 
of the manual. 


Chapter 2 describes the actions you must take at assembly time to prepare adequately for all 
intended file I/O processing through FCS. This chapter describes the data structures and working 
storage areas that you must define within a particular program to use any of the File Control 
Services. Until you are thoroughly familiar with this chapter, you are advised to postpone reading 
subsequent chapters. 


Chapter 3 describes the run-time macro calls that allow you to manipulate files and to perform I/O 
operations. 


Chapter 4 describes a set of run-time routines that perform I/O functions on files, such as reading 
and writing directory entries and renaming or extending files. 


Chapter 5 describes the structure of files for disk, DECtapes, and magnetic tapes supported by the 
IAS operating systems. 


Chapter 6 describes two collections of object library routines. The Get Command Line (GCML) 
routine and the Command String Interpreter (CSI) routine may be linked with the user task to 
perform operations that request command line input. Such input consists of file specifications that 
identify and control the files to be processed by your program. 


Chapter 7 describes the table-driven parser (TPARS), which provides you with the means to define 
and parse command lines in a unique user-designed syntax. 


Chapter 8 describes queuing files for printing. You can queue files for printing at both the MACRO 
and subroutine levels. 


Appendix A outlines the File Descriptor Block (FDB). 

Appendix B outlines the filename block (FNB). 

Appendix C describes the format and content of the file header block. 
Appendix D describes the format and content of the statistics block. 


Appendix E illustrates the structure of the index file of a Files-11 volume. 


Xvi 


Preface 


Appendix F summarizes a number of I/O-related system directives that form a part of the total 
resource management capabilities of the IAS Executive. 


Appendix G describes the format and content of the magnetic tape labels. 
Appendix H describes the QIO$ level interface to the file Ancillary Control Processors (ACPs). 


Appendix I lists IAS FCS library system generation options and provides a brief description of 
each. 


Appendix J illustrates the use of the macro calls that create and initialize the FDB. The appendix 
presents sample programs that include some of the macro calls used for processing files. 


Appendix K lists the error codes returned by the system. 
Appendix L lists the field-size symbols. 


Associated Documents 


The following manuals provide additional information and might be useful for understanding I/O 
operation logic: 


e JAS Executive Facilities Reference Manual 
e IAS Task Builder Reference Manual 
¢ PDP-11 MACRO-11 Language Reference Manual 


In addition, you might documentation for programming in any of the PDP-11 languages helpful. 


Conventions 


The following conventions are observed in this manual: 


Convention Meaning 
MCR> This is the explicit prompt of the Monitor Console Routine (MCR). 
PDS> This is the explicit prompt of the Program Development System (PDS). 


UPPERCASE Uppercase letters in a command line indicate letters that must be entered as they are shown. 
For example, utility switches must always be entered as they are shown in format specifications. 


command Where short forms of commands are allowed, the shortest form acceptable is represented by 
abbreviations uppercase letters. The following example shows the minimum abbreviation allowed for the PDS 
command DIRECTORY: 
PDS> DIR 


lowercase Any command in lowercase must be substituted for. Usually the lowercase word identifies the 
kind of substitution expected, such as a filespec, which indicates that you should fill in a file 
specification. For example: 
filename. filetype; version 


This command indicates the values that comprise a file specification; values are substituted for 
each of these variables as appropriate. 


xvill 


Convention 


/keyword, 
/qualifier, 
or 

/switch 


parameter 


[option] 


{} 


‘argument 


() 


[g,m] 


[directory] 


filespec 


Preface 


Meaning 


A command element preceded by a slash (/) is an MCR keyword; a DCL qualifier; or a task, 
utility, or program*switch. 


Keywords, qualifiers, and switches alter the action of the command they follow. 


Required command fields are generally called parameters. The most common parameters are 
tile specifications. 


Square brackets indicate optional entries in a command line or a file specification. If the brackets 
include syntactical elements, such as periods (.) or slashes (/), those elements are required 
for the field. If the field appears in lowercase, you are to substitute a valid command element if 
you include the field. Note that when an option is entered, the brackets are not included in the 
command line. 


Square brackets around a comma and an ellipsis mark indicate that you can use a series of 
optional elements separated by commas. For example, (argument [, ... ]) means that you 
can specify a series of optional arguments by enclosing the arguments in parentheses and by 
separating them with commas. 


Braces indicate a choice of required options. You are to choose from one of the options listed. 


Some parameters and qualifiers can be altered by the inclusion of arguments preceded by a 
colon. An argument can be either numerical (COPIES:3) or alphabetical (NAME:QIX). In DCL, 
the equal sign (=) can be substituted for the colon to introduce arguments. COPIES=3 and 
COPIES:3 are the same. 


Parentheses are used to enclose more than one argument in a command line. For example: 


SET PROT = (S:RWED, O:RWED) 


Commas are used as separators for command line parameters and to indicate positional entries 
on a command line. Positional entries are those elements that must be in a certain place in the 
command line. Although you might omit elements that come before the desired element, the 
commas that separate them must still be included. 


The convention [g,m] signifies a User Identification Code (UIC). The g is a group number and the 
m is a member number. The UIC identifies a user and is used mainly for controlling access to 
files and privileged system functions. 


This might also signify a User File Directory (UFD), commonly called a directory. A directory is 
the location of files. 


Other notations for directories are: [ggg,mmm], [ufd], [R], and [directory]. 
The convention [directory] signifies a directory in the same [g,m] form as the UIC. 


Where a UIC, UFD, or directory is required, only one set of brackets is shown (for example, 
[g.m]). Where the UIC, UFD, or directory is optional, two sets of brackets are shown (for 
example, [[g,m]}). 


A full file specification includes device, directory, file name, file type, and version number, as 
shown in the following example: 


DL2: [46,63] INDIRECT.TXT;3 


Full file specifications are rarely needed. If you do not provide a version number, the highest 
numbered version is used. If you do not provide a directory, the default directory is used. Some 
system functions default to particular file types. Many commands accept a wildcard character (*) 
in place of the file name, file type, or version number. Some commands accept a filespec with a 
DECnet node name. 


A period in a file specification separates the file name and file type. When the file type is not 
specified, the period may be omitted from the file specification. 
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KEYNAME 
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pood 


Meaning 

A semicolon in a file specification separates the file type from the file version. If the version is not 
specified, the semicolon may be omitted from the file specification. 

The at sign invokes an indirect command file. The at sign immediately precedes the file 
specification for the indirect command file, as follows: 

@filename[.filetype; version] 

A horizontal ellipsis indicates the following: 

¢ Additional, optional arguments in a statement have been omitted. 


¢ The preceding item or items can be repeated one or more times. 
* Additional parameters, values, or other information can be entered. 


A vertical ellipsis shows where elements of command input or statements in an example or figure 
have been omitted because they are irrelevant to the point being discussed. 


This typeface denotes one of the keys on the terminal keyboard, for example, the RETURN key. 


The symbol | CTRU/a| means that you are to press the key marked CTRL while pressing another 
key. Thus, | CTRL/Z| indicates that you are to press the CTRL key and the Z key together in this 


fashion. is echoed on some terminals as “Z. However, not all control characters echo. 


A lowercase n indicates a variable for a number. 


A symbol with a 1- to 3-character abbreviation, such as fq or [RET], indicates that you press a key 
on the terminal. For example, indicates the RETURN key, |LF| indicates the LINE FEED key, 
and indicates the DELETE key. 
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1.1 


File Control Services 


This chapter describes the file control services (FCS) features available for IAS users. It defines 
some of the terminology used throughout the manual. FCS enables you to perform record-oriented 
and block-oriented I/O operations, as well as additional operations required for file control. Open, 
close, wait, and delete are some of these additional operations. The term FCS, as used in this 
manual, is a substitute for FCSRES, a memory-resident library. This memory-resident library 
contains commonly used routines that are linked with your task at task-build time. These routines 
may also be linked with your task from a system object module library (SYSLIB.OLB). The three 
kinds of FCS are as follows: 


Library Description : 
ANSI Supports American National Standards Institute (ANS!) format magnetic tape and big buffers. 
Non-ANSI Does not support ANSI tape or big buffers. 

Multibuffered Supports ANSI tape, big buffers, and multiple buffers. 


When your task uses functions such as OPEN$, which opens a file, and CLOSE$, which closes a 
file, the task builder (TKB) resolves the address of these routines in FCSRES, thereby eliminating 
these routines from your task image. As a result, FCS routines do not significantly increase the 
size of your task image. If you do not link your task with FCSRES at task-build time, the routines 
must come from SYSLIB and are included in your task image, which increases its size. These 
routines, consisting of pure, position-independent code, provide an interface to the file system, 
enabling you to read and write files on file-structured devices and to process files by using logical 
records. 


Your program regards logical records as data units that are structured in accordance with 
application requirements, rather than as physical blocks of data on a particular storage medium. 
To meet the application’s requirements, FCS allows a collection of data—distinct logical records—to 
be written to a file in a way that enables you to retrieve the data from the file without having to 
know the exact format in which it was written to the file. FCS, therefore, is transparent to your 
task; records can be read or written in logical units that are consistent with particular application 
requirements. 


To invoke FCS functions from your task or application, your task issues macro calls to specify 
desired file control operations. The FCS macros are called at assembly time to generate code 
for specified functions and operations. The macro calls provide the system-level, file control 
primitives with the necessary parameters to perform the file access operations that you request 
(see Figure 1-1). 


Key Terms Used Throughout This Manual 


Following are terms used throughout this manual; they have unique definitions in the context of 
FCS operations. 


File Control Services 


Figure 1-1 File Acess Operation 


User—Issued Macro Call 


File Control Services 


File Control Primitives 


Peripheral Device Hardware 


(For Example, Disk, VT220) 


File Descriptor Block 


The File Descriptor Block (FDB) is the data structure that provides FCS with information needed 
to perform I/O operations on a file. The space for this data structure is allocated in your program 
by issuing the FDBDF$ macro call (see Chapter 2). Each file to be opened simultaneously by your 
program must have an associated FDB. Portions of the FDB, which may be defined by you or the 
system, are maintained by FCS. Assembly-time or run-time macro calls are provided for you to 
initialize the FDB. The format and content of the FDB are detailed in Appendix A. 


Filename Block 


The filename block is the portion of the FDB that contains the various elements of a file 
specification (see the File Specification entry in this section) that FCS uses. Initially, as a file 

is opened, FCS fills in the filename block with information that you specify and that is taken from 
the data-set descriptor or the default filename block (see the following subsections). Chapter 2 
describes how FCS fills in the filename block from a file specification; the format and content of the 
filename block are described in Appendix B. 
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Default Filename Block 


The default filename block is an area you allocate within your program by issuing the NMBLK$ 
macro call (see Chapter 2) that contains the various elements of a file specification. You create 
the default filename block; whereas, the filename block within the FDB is maintained by FCS. 
You create the default filename block to supply file specifications to FCS that are not otherwise 
available through the data-set descriptor (see the next entry). FCS takes these file specifications 
and creates a parallel structure in the FDB that contains information that FCS requires during 
execution time in opening and operating on files. 


Thus, the terms “default filename block” and “filename block” refer to separate and distinct 

data structures. These distinctions should be kept in mind whenever these terms appear in this 
manual. These areas are structurally identical, but they are created and used differently, and they 
may contain different information at different times. 


Data-Set Descriptor 


The data-set descriptor is a 6-word block in your program that contains the sizes and the addresses 
of American Standard Code for Information Interchange (ASCID data strings that together 
constitute a file specification (see Section 1.9). This 6-word block, which you also create, is 
described in detail in Chapter 2. Unless the filename block in the FDB has been initialized, 

you must provide FCS with data-set descriptor or default filename block information before the 
specified file can be opened. 


Data-Set Descriptor Pointer 


The data-set descriptor pointer is an address value that points to the 6-word data-set descriptor 
within your program. This address value is stored in the FDB, allowing FCS to access a file 
specification that you created in the data-set descriptor. 


File Specification 


The file specification is the unique file identification that names a file, specifies the location, and 
allows the location to be explicitly referenced by any task. The operating system, or your task, 
must refer to files by using a file specification. The file specification contains specific information 
that must be made available to FCS before that file can be opened. See Section 1.9 for a description 
of a file specification. 


File Storage Region 


The file storage region (FSR) is an area of memory that you reserve for use in I/O operations (see 
Section 1.7.3). You can allocate this area by issuing the FSRSZ$ macro call in your program (see 
Chapter 2). 


Important FCS Characteristics 
You should be aware of the following FCS characteristics when using I/O facilities: 


¢ I/O operations initiated by READ$ and WRITE$ macros are asynchronous; you are responsible 
for coordinating all block I/O activity. 


¢ I/O operations initiated by GET$ and PUT$ macros are synchronized entirely by FCS; control 
is not returned to your program until the requested GET$ or PUT$ operation is complete. 


¢ FCS macro calls save and restore all registers, with the following exceptions: 
— The file-processing macro calls (see Chapter 3) and the run-time FDB initialization macros 


(see Chapter 2) place the File Descriptor Block (FDB) address in RO. 
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— Many of the file control routines (see Chapter 4) return requested information in the 
general registers. 


¢ The macro that defines and allocates the space for the FDB is the FDBDF$ macro (see Chapter 
2). Once the FDB is allocated, necessary information can be placed in this data construct 
through any logical combination of assembly-time or run-time macro calls (see Chapter 2). 
Certain information must be present in the FDB before FCS can open and operate on a 
specified file. 


¢ For each assembly-time FDB initialization macro call, a corresponding run-time macro call is 
provided that supplies identical information. Although both sets of macro calls (see Chapter 
2, Table 2-1) place the same information in the FDB, each set does so in a different way. The 
assembly-time calls generate BYTE or .WORD directives that create specific data, while the 
run-time calls generate MOV or MOVB instructions that place desired information in the FDB 
during program execution. 


e If an error condition is detected during any of the file-processing operations described in 
Chapter 3, or during the execution of several of the file control routines (see Chapter 4), the 
Carry bit in the Processor Status Word (PSW) is set, and an error indicator is returned to FDB 
offset location F.ERR. 


NOTE: When you use the READ$ or WRITE$ macros to execute system I/O, the I/O status 
block (OSB) parameter must be specified for FLERR and the Carry bit to be properly 
returned (see Chapter 3). 


If the address of a user-defined error-handling routine is specified as a parameter in any of the 
file-processing macro calls, a jump to subroutine program counter (JSR PC) instruction to that 
error-handling routine is generated. The routine is then executed if the Carry bit in the PSW is 
set. 


FCS Data Structures 


In addition to generating calls to FCS subroutines, FCS macros issued by your task create and 
maintain certain data structures that file I/O operations require. These required data structures 
include the following: 


¢ A File Descriptor Block (FDB) that contains information necessary for processing the file. 


¢ A data-set descriptor that FCS accesses to obtain ASCII file name information required to open 
a specified file. 


e A default filename block that FCS accesses to obtain default file name information to open a 
specified file. FCS accesses the default filename block when complete file information is not 
specified in the data-set descriptor. 


¢ A file storage region (FSR) that FCS uses for working storage. The FSR is described in Section 
1.3.3. 


File Descriptor Block 


The File Descriptor Block (FDB) contains information that FCS uses to open and process files. One 
FDB is required for each file that your program opens simultaneously. You initialize some portions 
of the FDB with assembly-time or run-time macro calls, and FCS maintains other portions. Each 
FDB has the following five sections that contain information that your task or the system defines: 


e § 6File attribute section 
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¢ Record or block access section 
¢ File open section 
¢ Block buffer section 


e Filename block portion 


The information stored in the FDB depends upon the characteristics of the file to be processed. The 
FDB and the macro calls that cause values to be stored in this structure are described in detail in 
Chapter 2. Appendix A describes the format and the content of the FDB. 


Data-Set Descriptor and Default Filename Block 


You must specify either a data-set descriptor or a default filename block for each file that you 
intend to open. These data structures provide FCS with the file specifications required for opening 
a file. Although either the data-set descriptor or the default filename block is usually specified, you 
may also specify both for the same file. The data-set descriptor and the default filename block are 
further described in detail in Chapter 2. 


When a file is being opened using information already present in the filename block, neither the 
data-set descriptor nor the default filename block is accessed by FCS for required file information. 
This method of file access, which is termed “opening a file by file ID,” is an efficient means of 
opening files. Chapter 2 describes this process in detail. 


File Storage Region 


The file storage region (FSR) is an area allocated in your program as working storage for record I/O 
operations (see Section 1.7). The FSR consists of four program sections that are always contiguous. 
These program sections exist for the following purposes: 


$$FSR1 This area of the FSR contains the block buffers and the block buffer headers for record 1/O 
processing. You determine the size of this area at assembly time by issuing the FSRSZ$ macro 
call (see Chapter 2). The number of block buffers and associated headers is based on the number of 
files that you intend to open simultaneously for record I/O operations. 


$$FSR2 This area of the FSR contains impure data that FCS uses and maintains when performing both record 
and block I/O operations. Portions of this area are initialized at task-build time, and other portions are 
maintained by FCS. 


The size of the FSR can be changed, if desired, at task-build time. Chapter 2 shows you how to do 
this. 


File Access Methods 


IAS systems support both sequential and random access to data in files. Sequential access devices 
include magnetic tapes and card readers. Random access devices include disks. The sequential 
access method is device independent; that is, sequential access is usable on both record-oriented 
and random access devices (for example, card readers and disks). You can use the random access 
method only for random access devices. 
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Data Formats for File-Structured Devices 


Data is transferred between peripheral devices and memory in blocks. A data file consists of 
virtual blocks, each of which may contain one or more logical records created by your program. In 
FCS terms, a virtual block in a file consists of 512;9 bytes for random access devices. The size of 
the logical records in the virtual blocks is under the control of the program that originally wrote 
the records. 


When creating a new file, your program can specify that the records in the file will differ in size. 
Such records are known as variable-length records. Conversely, if your program indicates that all 
records in the new file will be equal in size, the records are known as fixed length. 


There are two types of variable-length records: sequenced and nonsequenced. Both must be 
word aligned; that is, each record must be stored as an even number of bytes. Sequenced 
variable-length records are preceded by a 2-word record header. The first word contains the length 
of the record (in bytes), and the second word contains the value of the sequence number as shown 
in Figure 1-2. The record length information is used to determine the end of each record and the 
beginning of its successor. Note that the word containing the sequence number is included in the 
record length. 


Figure 1-2 Sequenced Variable-Length Record 


0 
Record Length n (in Bytes) 
Sequence Number 


1 


Nonsequenced variable-length records are preceded by a single-word record header containing the 
length of the record as shown in Figure 1-3. 


Both fixed- and variable-length records are aligned on a word boundary. Any extra byte that 
results from an odd-length record is simply ignored. It is not included in the record length. (The 
extra byte is not necessarily a 0 byte.) 
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Figure 1-3 Nonsequenced Variable-Length Record 
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Virtual blocks and logical records within a file are numbered sequentially, each starting at 1. A 
virtual block number is a file-relative value; whereas, a logical block number is a volume-relative 
value. Ordinarily, records may cross block boundaries. Crossing block boundaries means that 
the beginning of a record can fill out the end of a block, while the rest of the record occupies the 
beginning of the next block. 


Data Formats for ANSI Magnetic Tape 


You can use both fixed- and variable-length records on magnetic tape; their format conforms to the 
ANSI standard. 


On magnetic tape, a virtual block corresponds to a physical record. The default length of a block is 
512 bytes. Its length can be changed to any value from 8 to 819219 bytes (14 to 819219 bytes for a 
write function) with the use of the FDBF$ macro (see Chapter 2). Records are not allowed to cross 
block boundaries. 


Fixed-length records are packed into a block with no control information and no padding for 
alignment. The block is truncated so that it ends at the word boundary immediately following the 
last record that will fit in the block buffer. 


Variable-length records are preceded by a 4-byte count field, which is expressed in decimal in 
ASCII characters. The count includes the length of the record and the 4-byte count field. After the 
last record in a block (if there is any space left in the block), a caret character (*, ASCII code 136) 
appears where the next byte count should be, signaling the end of data in that block. 


Biock I/O Operations 


Block I/O operations provide an efficient means of processing file data because such operations do 
not involve the blocking and deblocking of records within the file. Also, block I/O operations permit 
your task to read or write files in an asynchronous manner; that is, control may be returned to 
your program before the requested I/O operation is completed. 
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The read and write macro calls (READ$ and WRITE$) allow your task to read and write virtual 
blocks of data to and from a file without regard to logical records within the file. (See Chapter 3 for 
a description of READ$ and WRITE$ macro calls.) When your task uses block I/O, the number of 
the virtual block to be processed is specified as a parameter in the appropriate READ$ or WRITE$ 
macro call. The virtual blocks so specified are processed directly in a reserved buffer in your task’s 
memory space. Your task can use READ$ and WRITE$ only on block-structured devices. 


You are responsible for synchronizing all block I/O operations. Such asynchronous operations can 
be coordinated through an event flag (see Chapter 2) specified in the READ$/WRITE$ macro call. 
The system uses the event flag to signal the completion of a specified block I/O transfer, enabling 
you to coordinate those block I/O operations that are dependent on each other. 


Record I/O Operations 


Sequential access mode I/O operations can be performed for both fixed- and variable-length records. 
Random access mode I/O operations can be performed only for fixed-length records. Your program 
accesses records randomly by specifying a record number. This number represents the position 

of the desired record within the file (viewing the file as an array of fixed-sized records, with the 
number 1 representing the first record physically present in the file and n the last). 


The GET$ and PUT$ macro calls (see Chapter 3) are provided for processing individual records in 
files. Using the FSR block buffers (see Section 1.3.3), the GET$ and PUT$ routines perform the 
necessary blocking and deblocking of records within the virtual blocks of the file, allowing your 
program to access logical records. Successive GET$ or PUT$ operations in random access mode 
can access records anywhere within the file. To do so, your program need only modify the record 
number specified as part of the random record operation. After each such random operation, FCS 
increases by 1 the record number used in the operation. If your program does not again modify 
this number prior to issuing another record operation, the record actually accessed is the next 
sequential record in the file. 


In contrast to block I/O operations, all record I/O operations are synchronous; that is, control is 
returned to your program only after the requested I/O operation is completed. 


Because GET$ or PUT$ operations process logical records within a virtual block, only a limited 
number of GET$ or PUT$ operations result in an actual I/O transfer (for example, when the end of 
a data block is reached). Therefore, all GET$ or PUT$ I/O requests do not necessarily involve an 
actual physical transfer of data. 


The data flow during record I/O operations is shown in Figure 1—4. Note that blocks of data are 
transferred directly between the FSR block buffer and the device containing the desired file. The 
deblocking of records during input occurs in the FSR block buffer, and the blocking of records 
occurs in the FSR block buffer during output. Note also that FCS serves as your task’s interface to 
the FSR block buffer pool. All record I/O operations, which are initiated through GET$ and PUT$ 
macro calls, are synchronized by FCS. 


Record I/O Data- Transfer Modes 


By using record I/O, a program can gain access to a record in either of the following two ways after 
the virtual block has been transferred into the FSR from a file: 


¢ In move mode, by specifying that individual records are to be moved from the FSR block buffer 
to a record buffer that you have defined (see Figure 1—4) 


File Control Services 


Figure 1-4 Record I/O Operations 


Block Buffer Pool 


$$FSR2 
Impure Data 


¢ In locate mode, by referencing a location in the File Descriptor Block (see Section 1.3.1) that 
contains a pointer to the desired record within the FSR block buffer 


Move Mode 


Move mode requires that data be moved between the FSR block buffer and a record buffer that you 
have defined. For input, data is first read into the FSR block buffer from a peripheral device and 
then moved to your task’s record buffer for processing. For output, your program builds a record 
in your task’s record buffer; FCS then moves the record to the FSR block buffer, from which it is 
written to a peripheral device when the entire block is filled. 


Move mode simulates the reading of a record directly into your task’s record buffer; thus, the 
blocking and deblocking of records is transparent. 


Locate Mode 


Locate mode enables your task to access records directly in the FSR block buffer. Consequently, 
there is normally no need to transfer data from the FSR block buffer to your task’s record buffer. 
To access records directly in the FSR block buffer, refer to locations in the File Descriptor Block 
(see Section 1.3.1 and Appendix A) that contain values defining the length and the address of the 
desired record within the FSR block buffer. These values are present in the FDB as a result of 
FCS macro calls that you issued. 


Program overhead is reduced in locate mode because records can be processed directly within the 
FSR block buffer. Moving data to your task’s record buffer in locate mode is required only when 
the last record of a virtual block crosses block boundaries. 
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Multibuffering for Record 1/O 


By supporting multiple buffers for record I/O, FCS provides the ability in multibuffered FCS to 
read data into buffers in anticipation of user program requirements and to write the contents 

of buffers while your program is building records for output. (Multibuffered FCS is a SYSGEN 
option.) You can thus overlap the internal processing of data with file I/O operations, as illustrated 
in Figure 1—5. 


When your task uses read-ahead multibuffering, the file must be sequentially accessed to derive 
full benefit from multibuffering. For write-behind multibuffering, you can use any file access 
method with full benefit. 


When your task uses multibuffering, you must allocate sufficient space in the FSR for the total 
number of block buffers in use at any given time. The FSRSZ$ macro call (see Chapter 2) allocates 
space for FSR block buffers. 


Figure 1-5 Single Buffering Versus Multibuffering 
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1.7.2.1 Multibuffering Performance 
Multibuffering can improve performance for I/O-bound tasks under certain circumstances. 
However, multibuffer processing in random mode is not very efficient. Multibuffering in random 
mode always requires a user record buffer. If one is not supplied, the task’s low memory may be 
overwritten and the task may abort. ‘ 


For example, consider an I/O-bound task running as the dedicated or highest priority application 
on a system. For such a task, multibuffering can decrease overall processing time by enabling 


overlap of I/O and task execution. 


However, if other tasks run at the same priority as that of the application task described 
previously, then an overlap of I/O and task execution is already achieved among these tasks 
without multibuffering. In this case, multibuffering would use up address space and pool without 
improving execution speed. If virtual and physical address space is available, big buffering would 
improve performance (see Section 1.7.3). However, big buffer processing in random mode is not 
very efficient. 
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Big Buffering for Record /O 


If the task uses large records or operates on clusters of records, big buffering is advantageous. The 
use of big buffering assumes that it is reasonable to use more task address space and physical 
memory for increased buffer space, and it is reasonable to use more pool for the increased number 
of outstanding I/O packets. 


Big buffering reduces the number of disk accesses by allowing multiblock input and output. 
Normally, the disk accesses for GET$ or PUT$ operations are performed one sector at a time. 
Using FCS big buffers allows you to read or write a specified number of sectors in a single 
operation. 


When using big buffering in random mode, a user task record buffer is always required. If one 

is not supplied, the task’s low memory may be overwritten and the task may abort. Using big 
buffering with random GET$ and PUT$ can cause data to be lost from the end of a file. In this 
case, a directory of the file would indicate more blocks in use than it had allocated. To prevent this 
condition from happening, follow these steps: 


1 Preallocate enough space to make writing an extension unnecessary. 
2 Execute a FLUSH operation after the highest-numbered record is written by a PUT$ macro. 


3 After a PUT$ macro, arrange not to execute any GET$ macro that could cause the file to 
extend. 


To use big buffers, you must select the buffer size and specify that buffer size in the parameter 
lists for each occurrence of both the FSRSZ$ macro and the FDBDF$ macro in your program. 


You should choose a buffer size that is a multiple of 51239 bytes, the size of one disk block. Because 
the default amount allocated by a file extend is five blocks and disks often contain many 5-block 
files or parts of files, a buffer size of five blocks is generally a good choice. Larger amounts may 
increase performance, but note that you are trading large amounts of memory for speed. 


You must reserve the buffer space in your program, and you must specify the buffer size to the 
FDB. The FSRSZ$ macro allows you to specify the total buffer space needed. Specify 51219 bytes 
for each normal disk file, plus the buffer size that you have selected for each big buffered file. For 
example, assume that a program has three files: one normal file (512;9-byte buffer); one file with 
a big buffer size of three blocks; and one file with a big buffer size of five blocks. The following call 
to the FSRSZ$ macro reserves the space properly: 


FSRSZ$ = 3,<<1+3+5>*512.> 


In the FDB of each file that has a big buffer, you must override the default buffer size by using 
either the FDBF$A macro or the FDBF$R macro. For a file with five blocks as a big buffer, the 
assembly-time macro call is as follows: 


FOBFSA ,<5*512.> 


On IAS systems, the SYSLIB provided as the default library contains all the proper FCS modules 
for big buffer support. 
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Shared Access to Files 


The Files-11 disk architecture permits shared access to files according to established conventions. 
You can issue one of two macro calls, among several available in FCS for opening files, to invoke 
these conventions. The OPNS$x macro call (see Chapter 3) specifically opens a file for shared 
access. The OPEN$x macro call (see Chapter 3), on the other hand, invokes generalized open 
functions that have shared-access implications only in relation to other I/O requests subsequently 
issued. Both macro calls take an alphabetic suffix that specifies the type of operation being 
requested for the file, as follows: 


Read existing file. 

Write (create) a new file. 

Modify existing file without extending its length. 
Update existing file and extend its length, if necessary. 


>czs Dz 


Append data to end of existing file. 


The suffix R applies to the reading of a file; whereas, the suffixes W, M, U, and A all apply to the 
writing of a file. You can use the OPNS$x and OPEN$x macro calls as follows for shared access to 
files: 


1 When the OPNS$R macro call is issued, read access to the file is granted unconditionally, 
regardless of the presence of one or more concurrent write-access requests to the file. (The 
OPNS$R macro call permits concurrent write accesses to the file while it is being read.) 
Subsequent write-access requests for this same file are honored. Thus, several active 
read-access requests and one or more write-access requests may be present for the same 
file. However, multiple tasks simultaneously accessing the file for write operations are subject 
to certain restrictions, as detailed in number 2. 


2 While FCS allows concurrent write-access requests through the use of the OPNS$W, OPNS$M, 
OPNS$U, and OPNS$A macro, synchronizing access to the file is your task’s responsibility. To 
avoid the retrieval or storage of inconsistent data, each task must implement and use some 
mechanism, which you define, ensuring that the file is serially accessed. 


3 When the OPEN$R macro call is issued, read access to the file is granted, provided that 
no write-access requests for that file are active. (The OPEN$R macro call does not permit 
concurrent write access to the file while it is being read.) 


Note from the previous text that readers of a shared file should be aware that the file may yield 
inconsistent data from request to request if that file is also being written. 


Shared access during reading does not necessarily mean that the access requests are all from 
separate tasks. A file could also be shared by a single task that has opened the file on several 
different logical unit numbers (LUNs). 


_ Table 1-1 shows the circumstances under which Files-11 permits a second file access when the file 


is opened for shared access. 


Table 1-1 Shared File Access 

First Access 
Second Access Read Shared Read Write Shared Write 
Read Yes Yes No No 
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Table 1-1 (Cont.) Shared File Access 


First Access 


Second Access Read Shared Read Write Shared Write 
Shared Read Yes Yes Yes Yes 
Write No Yes No No 
Shared Write No Yes No Yes 


File Specification Syntax 
A full file specification has the following elements, in the order listed: 


device 
directory 
name 


type 
version 


A file specification has the following format: 
device:|directory]filename filetype;version 
An example of a full file specification follows: 
LB:[1,*]SUPLIB.OLB;0 is a full file specification. 


Device 


The device element of the file specification names the device on which the file resides. For 
unit-record devices, such as terminals and line printers, this is the only significant element in 
the file specification. 


The device specification consists of two alphabetic characters specifying the device name, followed 
by a 0- to 2-character octal numeric string specifying the device unit number, followed by a 
colon (:). FCS converts lowercase alphabetic characters to uppercase before passing them to 

the operating system. The device unit number must not exceed 773; if no unit number is given, 
FCS assumes unit 0. 


For example: 


db2 and DBO2 Indicate equivalent device specifications. 
SY and sy00 Indicate equivalent device specifications. 
login and LOGIN Indicate equivalent logical device specifications. 


Directory 


The directory element of the file specification names the directory through which the file can be 
found on the device. For ANSI magnetic tape files, this element is not significant (see Appendix A). 


If you use numbered directories, the directory specification can take either of the following forms: 


[group,member] 
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or: 
<group, member> 


Note that the delimiting characters ([] or <>) and the comma (,) must appear as shown. The group 
and member subelements each consist of a 1- to 3-digit octal number in the range of 0g to 3773. In 
situations where wildcards are permitted, you can substitute a single asterisk (*) character for the 
group or member subelement, or both, to indicate that all such elements are acceptable. 


You can explicitly request the current default directory by specifying [] or <> as the directory 
specification. For example, [27,36] and <027,036> are equivalent directory specifications. 


The following list shows the use of various wildcard substitutions: 


Directory 

Specification Meaning 

[27,"] Indicates all members in group 27. 

(","] Indicates all User File Directories (UFDs). 

["] Indicates all UFDs (for named directories only). 

{] Indicates the current default directory (named directories only). 
Name 


The name element of the file specification is the name by which the file is known in the directory. 
The name specification is a 0- to 9-character alphanumeric string. That is, the alphabetic 
characters A to Z and the numbers 0 to 9 are allowed. FCS converts lowercase alphabetic 
characters to uppercase before passing them to the operating system. 


In situations where wildcards are permitted, you can substitute an asterisk (*) character in the 
name string for any string including the null string. 


For example, the following names are acceptable within a file specification: 


MyFile.; Interpreted as MYFILE.. 


* 


P Matches file specifications with null types and versions. 
#,; Interpreted as the null name of 0 length. 


Type 

The type element of the file specification is the type by which the file is known in the directory. The 
type specification consists of a period (.) followed by a 0- to 3-character alphanumeric string. FCS 
converts the lowercase alphabetic characters to uppercase before passing them to the operating 
system. In situations where wildcards are permitted, you can substitute asterisks for any string 
including the null string. 


The following examples show some of the conversions that FCS makes: 


FCS 
File Type Interpretation 
dat Interpreted as .DAT. 
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FCS 
File Type Interpretation 
Interpreted as all types. 


Interpreted as the null type. 


Version 


The version element of the file specification provides the version number by which the file is known 
in the directory. The version specification consists of a semicolon (; ) followed by a 0- to 5-digit octal 
number in the range of 0 to 77777. 


In situations where wildcards are permitted, you can substitute a single asterisk for the octal 
number to indicate that all versions are acceptable. In situations where you are specifying a file 
that already exists, you can substitute the two characters “—1” for the octal number to specify the 
lowest-numbered version of the file that is known to the directory. 


You can specify a version number of 0 or the null version to indicate either of the following: 


¢ The highest-numbered version of the file that is known to the directory, when the file already 
exists 


¢ A version number one greater than the highest-numbered version of the file (if any) known to 
the directory, when you are creating a new directory entry 


The following show some conversions that FCS makes regarding version numbers: 


55 and ;0005 Indicates equivalent versions. 

: Indicates all versions. 

-1 Indicates the lowest-numbered version. 

; Indicates the null version; this is equivalent to ;0. 

For compatibility with other systems, FCS access methods can process version specifications 


beginning with a period (.) instead of a semicolon (;) when the presence of a type specification 
eliminates ambiguity. 


ANSI Magnetic Tape File Specification Syntax 


The file specification format specific to magnetic tapes consists of the following elements, in the 
order listed: 


device 
directory 
quoted string 
version 


Device 


The device element is the same as that described in Section 1.9.1. The device must be a magnetic 
tape device. 
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Directory 


The directory element is the same as that described in Section 1.9.2. This element has no meaning 
for ANSI magnetic tape files, and it is ignored if present. 


Quoted String 


FCS treats a quoted string as a unit representing both the name and type elements of a standard 
file specification. This mechanism allows expression of tape file names up to 17 characters in 
length that include the full set of ANSI “a” characters (some of which would otherwise be ignored 
or treated as element delimiters in a standard file specification). 


You specify an ANSI name by including the name in quotation marks (“name”). If the name itself 
contains full quotation marks ("), you must also precede each such character with an additional 
full quotation character ("). FCS converts any lowercase alphabetic characters to uppercase, 
strips the full-quotation marks that you have added, and passes the result to the operating system 
without further modification (including ANSI “a” characters such as space). 


The following examples show the results of FCS-processed quoted strings: 


“My File” Interpreted as MY FILE. 
““Don't Panic” Interpreted as “DON’T PANIC.” 
Version 


The version element of a magnetic tape file specification is the same as that for a conventional file 
specification (see Section 1.9.5). A version specification of ;0, ;-1, or the null version is interpreted 
as any version for magnetic tape files. 


1.10.4.1 Example Magnetic Tape File Specification 
An example of an ANSI magnetic tape file specification follows: 


MU1:"KIM’s file" specifies any version of KIM’S FILE on device MU1: 


The standard file specification format described in Section 1.9 can also be used with magnetic 
tapes; this permits file transport to nontape devices and file accessibility by the widest possible 
range of software. See Appendix G for additional information concerning the use of names in ANSI 
magnetic tape files. 


Generation of a Full File Specification 


When you specify the target file for an FCS operation, FCS generates a full file specification in the 
following manner: 


1 FCS parses the filename string to determine which elements are present. You need not 
provide a full file specification in the filename string; however, any elements present 
must be syntactically correct and in the proper order. FCS ignores any null, space, or tab 
characters that may be present in the string unless they occur within an ANSI magnetic tape 
quoted-string name. 


2 FCS processes the default filename block to determine which elements are present. You need 
not provide a full file specification in the default filename block. 
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3 If the filename string does not provide a full file specification, FCS obtains missing elements 
from the default filename block; if any elements are missing after this merge, FCS provides 
default values for them as follows: 


Device Defaults to the device to which the specified logical unit is currently assigned; If the specified 
logical unit is not assigned to any device, defaults to SY. 

Directory Defaults to the current directory. 

Name, type, Defaults to null. 

and version 


Routines Included in FCSRES 


Table 1-2 lists the routines contained in all forms of FCS. However, the routines included in the 
overlaid version FCSRES are placed into two overlay segments. The first overlay segment includes 
routines used for open, close, and associated user-accessible routines. The second overlay segment 
includes routines used for get, put, read, write, and other user-accessible routines. 


Table 1-2 FCSRES Routines 


Routine Name Module Name 


First Overlay Segment 


ASCIl UIC to Binary Conversion ASCPPN 
Assign Logical Unit Number ASSLUN 
Binary UIC to ASCII Conversion PPNASC 
Close CLOSE 
Delete File DELJMP, DELETE 
Delete File by Filename Block DEL 
Directory Primitives DIRECT 
Extend File EXTEND 
Expand Logical Name and Return .EXPLG 
Pointer to Expanded String 
File Storage Region Initialization FINIT 
Get Directory GETDIR 
Get Directory IID GETDID 
Mark for Deletion (Internal) MKDL 
Mark for Deletion (User Interface) MRKDL 
Octal to Decimal Conversion ODCVT 
Open OPNJMP, OPENR 
Parse PARSE 
Parse Device PARSDV 
Parse Directory PARSDI 
Parse File Name PARSFN 
Print $PRINT 
Rename RENAME 


File Control Services 


Table 1-2 (Cont.) FCSRES Routines 


Routine Name 


First Overlay Segment 


Request Logical Core Block 


Send Data to and Start a Subsidiary Task 


Truncate and Close File 
User Directive Primitives 


Second Overlay Segment 


Arithmetic Routines 

ASCII to Binary Conversion 

Binary to ASCII Conversion 

Convert Double Precision to Decimal 
Double Precision Arithmetic Routines 
Edit Message 

Edit Time and Date 

Exit with Status 

Read/Write File Storage Region 2 
Flush 

Get Record 

Obtain Library Attributes 

Octal to Binary Conversion 

Parse Command Line 


Point and Mark 

Position Record 

Put Record 

Qio 

Read Block 

Return Position 

User Device Control Function 
Wait 

Write Block 


Module Name 


RQLCB 
DSPAT 
TRNCLS 
UDIREC 


ARITH 
CATB 
CBTA 
CODMG 
DARITH 
EDTMG 
EDDAT 
EXST 
RWFSR2 
FLUSH 
GETJMP, GET 
FCSTYP 
-OD2CT 


CSii, .CSI2, 
.EXPLG 


PNTMRK 
POSREC 
GETJMP, PUT 
XQIOU 

READ 

POSIT 
CONTRL 
WAITU 
WRITE 
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This chapter describes the macro calls that your task must invoke to provide the necessary 
file-processing information for the File Descriptor Block (FDB). 


General Information 


The MACRO-11 programmer must establish the proper database and working storage areas within 
the particular program to perform I/O operations. You must do the following: 


1 Define a File Descriptor Block (FDB) for each file that your program is to open simultaneously 
(see Section 2.2). 


2 Define a data-set descriptor or a default filename block, or both (see Sections 2.5.1 or 2.5.2, 
respectively) if you intend to access these structures to provide file specifications that FCS 
requires. 


3 Establish a file storage region (FSR) within the program (see Section 2.6). (The initialization 
procedures for FORTRAN tasks are described in detail in the PDP-11 MACRO-11 Language 
Reference Guide.) 


Your task can place such information in the FDB in one of three ways: 

¢ By the assembly-time FDB initialization macro calls (see Section 2.3.1) 

¢ By the run-time FDB initialization macro calls (see Section 2.3.2) 

° By the file-processing macro calls (see Chapter 3) 

Data supplied during the assembly of the source program establishes the initial values in the FDB. 
Data supplied at run time can either initialize additional portions of the FDB or change values 


established at assembly time. Similarly, the data supplied through the file-processing macro calls 
can either initialize portions of the FDB or change previously initialized values. 


Table 2-1 lists the macro calls that generate FDB information. 


Table 2-1 Macro Calls Generating FDB Information 


Assembly-Time FDB Run-Time FDB File-Processing 
Macro Calls Macro Calls Macro Calls 
FDBDF$ (required) FDAT$R OPEN$ (all variations) 
FDAT$A FDRC$R CLOSE$ 
FDRC$A FDBK$R GET$ (all variations) 
FDBK$A FDOP$R PUTS$ (all variations) 
FDOP$A FDBF$R READ$ 
- FDBFS$A WRITE$ 
DELET$ 
WAITS 
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-MCALL Directive—-Listing Names of Required Macro Definitions 


You must list as arguments in a .MCALL directive all the assembly-time, run-time, and 
file-processing macro calls (see Table 2—1) that you intend to issue in a program. Doing so allows 
the required macro definitions to be read in from the System Macro Library during assembly. 


You must write the .MCALL directive and associated arguments in the program prior to writing 
any macro call in the execution code of the program. If the list of macro names is lengthy in the 
-MCALL statement, you must specify several .MCALL directives, each appearing on a separate 
source line. The availability of space within an 80-byte line of source code limits the number of 
such names that may appear in any one .MCALL statement. 


-MCALL arg!,arg2, ... ,argn 


Argument 


argi,arg2, ... ,argn 

Specifies a list of symbolic names that identify the macro definitions that you use in your program. 
If more than one source line is required to list the names of all desired macros, each additional line 
must begin with a .MCALL directive. 


For clarity in your source code, you may list the assembly-time, run-time, and file-processing macro 
names in each of three separate .MCALL statements; you may list the macro names alphabetically, 
or you may mix them. None of these optional arrangements have any effect whatever on retrieving 
macro definitions from the System Macro Library. 


If you are planning to invoke the command line processing capabilities of the Get Command Line 
(GCML) routine and the Command String Interpreter (CSI), you must list all the names of the 
associated macros as arguments in a .MCALL directive. GCML and CSI, ordinarily employed in 
system or application programs for convenience in dynamically processing file specifications, are 
described in detail in Chapter 6. 


The .MCALL directive is described in detail in the PDP-11 MACRO-11 Language Reference Guide. 
The sample programs in Appendix J also illustrate the use of the .MCALL directive. Note 

that these .MCALL directives appear as the first statements in the preparatory coding of these 
programs. 


The object routines described in Chapter 4 should not be confused with the macro definitions 
available from the System Macro Library. The file control routines, constituting a body of 
object modules, are linked into your program at task-build time from the system object library 
({1,1JSYSLIB.OLB). Consult Chapter 4 for a description of these routines. 


The following statements show sample uses of the .MCALL directive: 


-MCALL FDBDFS$,FDATSA, FDRCSA, FDOPS$A, NMBLKS, FSRSZS$,FINITS 
-MCALL OPENSR, OPENSW, GETS, PUTS, CLOSES 


Note 


You can use the macro FCSMC$ to declare the most commonly used FCS macros within the 
-MCALL format as follows: 


-MCALL FCSMCS 
FCSMCS 


FCS macros declared in this manner include: OPEN$x, OPNS$x, CLOSE$, READ$, WRITE$, 
WAIT$, GET$, PUT$, DELET$, FINIT$, FSRSZ$, FDBDF$, FDAT$x, FDRC$x, FDOP$x, FDBF$x, 
FDBK$x, and NMBLK$. If other macros are required, explicit .MCALL directives must be issued. 
One disadvantage of using this method to declare .MCALL directives is that unused macros may 
take up possibly critical assembler symbol table space, thus slowing down the assembly process. 
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File Descriptor Block 


The File Descriptor Block (FDB) is the data structure that provides the information FCS needs for 
all file I/O operations. Two sets of macro calls are available for FDB initialization: you can use one 
set for assembly-time initialization (see Section 2.3.1) and the other set for run-time initialization 
(see Section 2.3.2). Use the run-time macros to supplement or override information specified during 
assembly. The FDB sections are described in Appendixes A and B. 


Assembly-Time FDB Initialization Macros 


Assembly-time initialization requires that the FDBDF$ macro call be issued (see Section 2.3.1.1) to 
allocate space for and to define the beginning address of the FDB. Additional macro calls can then 
be issued to establish other required information in this structure. The assembly-time macros that 
accomplish these functions are described in the following sections. 


mconam$A pl,p2,...,pn 


Macro Name 
mcnam$A 
Specifies the symbolic name of the macro. 


Parameter 


p1,p2,...,pn 

Specifies the string of initialization parameters associated with the specified macro. A parameter 
may be omitted from the string by leaving its field between delimiting commas null. Assume, for 
example, that a macro call may take the following parameters: 


FDOPSA 2,DSPT,DENB 


Assume further that the second parameter field is to be coded as a null specification. In this case, 
the statement is coded as follows: 


FDOPSA 2,,DFNB 


A trailing comma need not be inserted to reflect the omission of a parameter beyond the last 
explicit specification. For example, the following macro call need not be specified as if the last 
parameter (DFNB) is omitted: 


FDOPSA 2,DSPT,DFNB 
FDOPSA 2,DSPT, 

Rather, such a macro call is specified as follows: 
FDOPSA 2,DSPT 


If any parameter is not specified, that is, if any field in the macro call contains a null specification, 
the corresponding cell in the FDB is not initialized and thus remains 0. 


Multiple values may be specified in a parameter field of certain macro calls. Such values are 
indicated by placing an exclamation point (!) between the values, indicating a logical OR operation 
to the MACRO-11 assembler. Specifying multiple values in this manner is mentioned throughout 
this manual if applicable to the macro call. 
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Throughout the descriptions of the assembly-time macros in this section and elsewhere in this 
manual, symbols of the form F.xxx or F.xxxx are referenced (for example, F.RTYP). These symbols 
are defined as offsets from the beginning address of the FDB, allowing specific locations within 
the FDB to be referenced. Thus, you can reference or modify information within the FDB without 
having to calculate word or byte offsets to specific locations. 


Using such symbols in either system software or your software also permits the relative position of 
cells within the FDB to be changed (in a subsequent release, for example) without affecting your 
current programs or the coding style employed in developing new programs. As a result, we highly 
recommend that you use them. 


2.3.1.1 FDBDF$—Allocate File Descriptor Block 
The FDBDF$ macro call is specified in a MACRO-11 program to allocate space within the program 
for an FDB. This macro call must be specified in the source program once for each input or output 
file that your program simultaneously opens during execution. Any associated assembly-time 
macro calls (see Sections 2.3.1.2 to 2.3.1.6) must then be specified immediately following the 
FDBDF$ macro if you want to initialize certain portions of this FDB during assembly. 


Macro Name and Label 
label: FDBDF$ 


label 

Specifies a symbol, which you specify, that names this particular FDB and defines its beginning 
address. This label is particularly significant in all I/O operations that require access to the data 
structure allocated through this macro call. FCS accesses the fields within the FDB relative to the 
address represented by this symbol. 


The following examples show how the FDBDF$ macro calls might appear in your source program: 


FDBOUT: FDBDFS$ *ALLOCATES SPACE FOR AN FDB NAMED 
7"FDBOUT" AND ESTABLISHES THE 
7BEGINNING ADDRESS OF THE FDB. 


FDBIN: FDBDES 7;ALLOCATES SPACE FOR AN FDB NAMED 
7;"FDBIN" AND ESTABLISHES THE 
7BEGINNING ADDRESS OF THE FDB. 


As noted earlier, the source program must embody one FDBDF$ macro call logically similar to 
these example macro calls for your program to access each file simultaneously. FDBs can be reused 
for many different files, as long as the file currently using the FDB is closed before the next file 

is opened. The only requirement is that an FDB must be defined for every simultaneously opened 
file. 


2.3.1.2 FDAT$A—Initialize File Attribute Section of FDB 
The FDAT$A macro call initializes the file attribute section of the FDB when a new output file is 
to be created. If the file to be processed already exists, the first four parameters of the FDAT$A 
initialization macro need not be specified because FCS obtains the necessary information from the 
first 14 bytes of the file attribute section. The file attribute section is in the header block of the 
specified file. (See Appendix C.) 


FDAT$A _rtyp,ratt,rsiz,cntg,aloc 
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Parameters 


rtyp 
Specifies a symbolic value that defines the type of records to be built as the new file is created. 
One of three values must be specified, as follows: 


R.FIX Indicates that fixed-length records are to be written in creating the file. 
R.VAR _ Indicates that variable-length records are to be written in creating the file. 
R.SEQ Indicates variable-length sequenced records are to be written in creating the file. 


The rtyp parameter initializes FDB offset location F.RTYP. The symbols R.FIX, R.VAR, and R.SEQ 
initialize the same location in the FDB and are mutually exclusive. 


ratt 


Specifies symbolic values that may be specified to define the attributes of the records as the new 
file is created. 


The following parameters initialize the record attribute byte (offset location F.RATT) in the FDB. 
The values FD.FTN and FD.CR are mutually exclusive and must not be specified together. Apart 
from this restriction, the combination (logical OR) of multiple parameters specified in this field 
must be separated by an exclamation point (for example, FD.CR!FD.BLK). 


Specify the following symbolic values, as appropriate, to define the desired record attributes: 


FD.FTN indicates that the first byte in each record is to contain a FORTRAN carriage contro! character. 


FD.CR Indicates that the record is to be preceded by a <LF> character and followed by a <CR> character when 
the record is written to a carriage control device (for example, a line printer or a terminal). 


FD.BLK Indicates that records cannot cross block boundaries. 


FD.PRN Indicates that the record is preceded by a word containing carriage control information; this value is the 
print file format attribute. Files that have this attribute set must also be sequenced files; that is, files that 
have the bit R.SEQ set in byte F.RTYP in the FDB. 


In a file with attribute FD.PRN, each record is associated with its own print format word, which describes 
the carriage control for that record, if the record is output to a unit record device such as a terminal or 
line printer. A program using FCS can read or write a file with attribute FD.PRN, but FCS ignores and 
does not interpret the format word. Thus, the Peripheral Interchange Program (PIP) correctly copies 
such a file from disk to disk, but a copy to TI may not achieve the desired carriage control. Note that 
FCS does not interpret the FD.PRN format word. 


Files with the print file format attribute are a subset of sequenced files. Sequenced files are identified by 
record type R.SEQ in FDB field R.RTYP. Sequenced files have records of variable length; each record 
is associated with a 1-word sequence number. (Note that sequential is not the same as sequenced. 
Sequential means that the file is not a Record Management Services (RMS) indexed or relative file. All 
sequenced files are also sequential.) 
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When a program is reading a sequenced file with FCS in record mode, FCS returns the record in the 
normal manner on a GET$; the sequence number is returned in FDB field FSEQN. Conversely, when 
writing a sequenced file with FCS in record mode, FCS writes the record in the normal manner and 
writes the associated sequence number from F.SEQN. 


The sequence number field can contain any pattern of bits. A frequent application of this field Is its use 
as a line number for text files. 


The difference between a file with attribute FD.PRN and any other sequenced file Is that the sequence 
number is considered to be the carriage control format word. This word has a particular meaning in a 
file with attribute FD.PRN. Each byte of the format word describes the carriage control for the associatec 
record. The low byte describes carriage control action that should occur before the record is printed; the 
high byte describes carriage control action that should occur after the record is printed. 


FCS operates on files with attribute FD.PRN in the same way that it operates on any other sequenced 
file. FCS uses the FDB field F.SEQN for the format word. Each byte of the format word is defined as 


follows: 

Bits 0-6 Bit 7 Meaning 

0 | 0 No carriage control. 
1-127 0 Bits 0-6 are a count of 


line records. 


Bits 0-4 Bit 5 Bit 6 Bit 7 Meaning 


1-310 0 0 1 Bits 0—4 define a 7-bit 
ASCII control character to be output. 
1-31 40 1 0 1 Bits 0-4 are translated 


as an 8-bit ASCII control 
character ranging from 
12819 to 15919 to be output. 


0 1 1 1 Reserved for future use. 


Because print format files must be sequenced files, FCS allows FD.PRN as an attribute of a new file 
only if record type R.SEQ is also specified. For example: 


FDBDFS$ ;Allocate space for FDB 
FDATSA 7Print file format 


FCS does not create a file with attribute FD.PRN that has a record type other than R.SEQ. In this case, 
~ FCS returns an error —4540, IE.RAT, "illegal attribute bits set.” 


rsiz 

Specifies a numeric value that defines the size (in bytes) of fixed-length records to be written to 
the file. This value, which initializes FDB offset location F.RSIZ, need not be specified if R.VAR 
has been specified as the record type parameter (for variable-length records). If R.VAR or R.SEQ 
is specified, FCS maintains a value in FDB offset location F. RSIZ that defines the size (in bytes) 
of the largest record currently written to the file. Thus, whenever an existing file containing 
variable-length records is opened, the value in F.RSIZ defines the size of the largest record within 
that file. By examining the value in this cell, a program can dynamically allocate record buffers fo 
its open files. 


cntg 


Specifies a signed numeric value that defines the number of blocks that are allocated for the file a: 
it is created. The signed values have the following significance: 
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Positive Value Indicates that the specified number of blocks is to be allocated contiguously when the file is 
created; It also indicates that the file is to be contiguous. 

Negative Value Indicates that the two's complement of the specified number of blocks is to be allocated when 
the file is created, though not necessarily contiguously; it also indicates that the file is to be 
noncontiguous. 


The cntg parameter, which has 15 bits of magnitude (plus a sign bit), initializes FDB offset location 
F.CNTG. . 


(You can specify an allocation of up to 24 bits by using the EEXXTND routine.) 


If you can estimate how long the file might be, it is more efficient to allocate the required number 
of blocks through this parameter when the file is created than to require FCS to extend the file 
when the file is written. (See the aloc parameter in the following text.) 


If this parameter is not specified, an empty file is created; that is, no space is allocated within the 
file as it is created. 


Issuing the CLOSE$ macro call at the completion of file processing resets the value in F.CNTG to 
0. Thus, the usual procedure is to initialize this location at run time just before opening the file. 
Reinitialization is necessary if the FDB is reused. 


aloc 

Specifies a signed numeric value that defines the number of blocks by which the file is extended, 
if FCS determines that file extension is necessary as records are written to the file. When the 
end of allocated space in the file is reached during writing, the signed value provided through this 
parameter causes file extension to occur, as follows: 


Positive Value Indicates that the specified number of blocks is to be allocated contiguously as additional 
space within the file; it also indicates that the file is to be contiguous. 

Negative Value Indicates that the two’s complement of the specified number of blocks is to be allocated 
noncontiguously as additional space within the file; it also indicates that the file is to be 
noncontiguous. 


NOTE: Once a file has had blocks allocated, all future file extensions cause the file to 
become noncontiguous, even when aloc is a positive value. 


This parameter, which also has 15 bits of magnitude (plus a sign bit), initializes FDB offset location 
F.ALOC. If this optional parameter is not specified, file extension occurs as follows: 


° If the number of virtual blocks yet to be written is greater than 1, the file is extended by the 
exact number of blocks required to complete the writing of the file. 


¢ If only one additional block is required to complete the writing of the file, the file is extended 
in accordance with the volume’s default extend value. 


The volume default extend size is established through the INITIALIZE or MOUNT command. The 
_ volume default extend size cannot be established at the FCS level; this value must be established 
when the volume is initially mounted. 


The following example statement shows a sample of an FDAT$A macro call. This statement 
initializes the FDB in preparation for creating a new file containing fixed-length, 80-byte records 
that will be allowed to cross block boundaries. For example: 


FDATSA R.FIX,,80. 
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In the previous example statement, the record attribute (ratt) parameter has been omitted, as 
indicated by the second comma (, ) in the parameter string. Also, the cntg and aloc parameters 
have been omitted. Their omission, however, follows the last explicit specification, and their 
absence need not be indicated by trailing commas in the parameter string. Because the aloc 
parameter has been omitted, file extension (if it becomes necessary) is accomplished in accordance 
with the current default extend size in effect for the associated volume. 


If more than one record attribute is specified in the ratt parameter field, such specifications must 
be separated by an exclamation point (!), as shown in the following macro: 


FDATSA R.VAR,FD.FTN!FD.BLK 


The previous macro call enables a file of variable-length records to be created. The records will 
contain FORTRAN vertical-formatting information for carriage control devices; the records will not 
be allowed to cross block boundaries. 


2.3.1.3 FDRC$A—Initialize Record Access Section of FDB 
The FDRC$A macro call initializes the record access section of the FDB, and the macro indicates 
whether to use record or block I/O operations in processing the associated file. 


If you want to use record I/O operations (GET$ and PUT$ macro, the FDRC$A or the FDRC$R 
macro call (see Section 2.3.2) establishes the FDB information necessary for record-oriented I/O. 
However, if you want to use block I/O operations (READ$ and WRITE$ macro calls), the FDBK$A 
macro call (see Section 2.3.1.4) or the FDBK$R macro call (see Section 2.3.2) must also be specified 
to establish other values in the FDB required for block I/O. In this case, portions of the record 
access section of the FDB are physically overlaid with parameters from the FDBK$A/FDBK$R 
macro call. 


You must appropriately initialize the FDB to indicate whether record or block I/O operations are tc 
process the associated file prior to issuing the OPEN$ macro call to initialize file operations. 


FDRC$A _racc,urba,urbs 


Parameters 


racc 

Specifies which variation of block or record I/O is to process the file. This parameter initializes 
the record access byte (offset location F.RACC) in the FDB. The first value shown next, FD.RWM, 
applies only for block I/O (READ$ or WRITE$) operations; all remaining values are specific to the 
following record I/O (GET$ or PUT$) operations: 


FD.RWM Indicates that READ$ or WRITE$ (block I/O) operations are to process the file. If this value Is not 
specified, GET$ or PUT$ (record 1/O) operations process the file by default. 


Specifying FD.RWM necessitates issuing an FDBK$A or an FDBK$R macro call in the program to 
initialize other offsets in the block access section of the FDB. Note also that the READ$ or WRITE$ 
macro call allows the complete specification of all the parameters required for block /O operations. 


FD.RAN Indicates that random access mode is to process the file. If this value is not specified, sequential 
access mode processes the file by default. See Chapter 1 for a description of random access mode. 


The following statement shows a sample FDRC$A macro call issued for a file that may be accessed in 
random mode: 
FDRCSA FD.RAN,BUF1,160. 


You specify the address of the task’s record buffer through the symbol BUF1, and you specify the size 
of the buffer (in bytes) by the numeric value 16040. . 


Preparing for I/O 


FD.PLC Indicates that locate mode is to process the file. If this value is not specified, move mode processes 
the file. 

FD.INS Indicates that a PUT$ operation performed within the body of the file shall not truncate the file. This 
value applies only for sequential files and therefore cannot be specified jointly with the FD.RAN 
parameter. 


If you specify more than one value in the record access (racc) field, an exclamation point (!) must 
separate the multiple values, as follows: 


FDRCSA FD.RAN!FD.PLC, BUF1,160. 


In addition to the functions described for the previous example, this example specifies that locate 
mode is to process the associated file. Note that the multiple parameters specified in the first field 
are separated by an exclamation point. 


If you want your task to perform a PUT$ operation within the body of a file, the POINT routine 

described in Chapter 4 may be called. This routine positions the file to a byte you specify within 

a virtual block in preparation for the PUT$ operation. The .POINT routine also permits a limited 
degree of random access to a file. 


If FD.INS is not specified, a PUT$ operation within the file truncates the file at the point of 
insertion; that is, the PUT$ operation moves the logical end-of-file (EOF) to a point just beyond the 
inserted record. However, no deallocation of blocks within the file occurs. 


Regardless of the setting of the FD.INS bit, a PUT$ operation that is in fact beyond the current 
logical end-of-file resets the logical end of the file to a point just beyond the inserted record. 


urba 

Specifies the symbolic address of your task’s record buffer used for GET$ operations in move and 
locate modes; it is also used for PUT$ operations in locate mode. This parameter initializes FDB 
offset location F.URBD+2, and urba is specified only for record I/O operations. 


urbs 

Specifies a numeric value that defines the size (in bytes) of your task’s record buffer used for 
GET$ operations in move and locate modes; it is also used for PUT$ operations in locate mode. 
This parameter initializes FDB offset location F URBD, and urbs is specified only for record I/O 
operations. 


You allocate and label a record buffer in a program by issuing a .BLKB or .BLKW directive. The 
address and the size of this area are then passed to FCS as the urba and the urbs parameters 
shown previously. For example, a task’s record buffer may be defined through a statement that is 
logically equivalent to the following: 


RECBUF: .BLKB 82. 
RECBUF is the address of the buffer and 8249 is its size (in bytes). 


Beginning a task’s record buffers on a word boundary can improve performance by allowing FCS to 
move the data with MOV instructions rather than MOVB instructions. 


Under certain conditions, you need not allocate a record buffer or specify the buffer descriptors 
(urba and urbs) for GET$ or PUT$ operations. These conditions are described in detail in Chapter 
3. 
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2.3.1.4 FDBK$A—Initialize Block Access Section of FDB 
The FDBK$A macro call initializes the block access section of the FDB when block I/O operations 
(READ$ and WRITE$ macro calls) are used for file processing. Initializing the FDB with this 
macro call allows you to read or write virtual blocks of data within a file. 


Use of the FDBK$A macro call implies that the FDRC$A macro call has also been specified, 
because the FD.RWM parameter of the FDRC$A macro call initially declares block I/O operations. 
Thus, for block I/O operations, the FDRC$A macro call must be specified, as well as any one of 
the following macro calls, to appropriately initialize the block access section of the FDB: FDBK$A, 
FDBK$R, READ$, or WRITE$. 


Issuing the FDBK$A macro call causes certain portions of the record access section of the FDB 

to be overlaid with parameters necessary for block I/O operations. Thus, the terms “record access 
section” and “block access section” refer to a shared physical area of the FDB that is functional for 
either record or block I/O operations. 


The block I/O and record I/O FDB-initialization macros use the same area of the FDB for different 
data. Therefore, if record I/O operations are to be employed, neither the FDBK$A nor the FDBK$R 
macro call must be issued. 


FDBK$A _bkda,bkds,bkvb,bkef,bkst,bkdn 


Parameters 


bkda 


Specifies the symbolic address of an area in your task’s memory space to be employed as a buffer 
for block I/O operations. This parameter initializes FDB offset location F. BKDS+2. 


bkds 


Indicates a numeric value that specifies the size (in bytes) of the block to be read or written when a 
block I/O request (READ$ or WRITE$ macro call) is issued. This parameter initializes FDB offset 
location F.BKDS. The size specified must be an even, positive (the sign bit must not be set) value; 
the maximum number of bytes that can be specified is 32,766. If an integral number of blocks is 
to be specified, the practical maximum number of bytes that can be specified is equal to 63 virtual 
blocks, or 32,25619 bytes. 


bkvb 


Specifies a dummy parameter for compatibility with the FDBK$R macro call. The bkvb parameter 
is not specified in the FDBK$A macro call for the reasons stated in item 4 of Section 2.3.2.1. In 
short, assembly-time initialization of FDB offset locations F. BKVB+2 and F.BKVB with a virtual 
block number is meaningless, because any version of the generalized OPEN$x macro call resets the 
virtual block number to 1 as the file is opened. Therefore, these cells can be initialized only at run 
time through either the FDBK$R macro call (see Section 2.3.2) or the I/O-initiating READ$ and 
WRITE$ macro calls (see Chapter 3). 


This dummy parameter should be reflected as a null specification (with a comma) in the parameter 
string only in the event that an explicit parameter follows. This null specification is required to 
maintain the proper position of any remaining field or fields in the parameter string. 


bkef 


Specifies a numeric value that specifies an event flag to be used during READ$ or WRITE$ 
operations to indicate the completion of a block I/O transfer. This parameter initializes FDB offset 
location F. BKEF; if not specified, event flag 3219 is used by default. 


The function of an event flag is described in further detail in Section 2.9.1. 
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bkst 


Specifies the symbolic address of a 2-word I/O status block (IOSB) in your program. If specified, 
this optional parameter initializes FDB offset location F.BKST. 


The IOSB, if it is to be used, must be defined and appropriately labeled at assembly time. Then, 
if you specify the bkst parameter, information is returned by the system to the IOSB at the 
completion of the block I/O transfer. This information reflects the status of the requested operation. 
If this parameter is not specified, no information is returned to the IOSB. 


NOTE: If an error occurs during a READ$ or WRITES operation that would normally 
be reported as a negative value in the first byte of the IOSB, the error is not reported 
unless you specify an IOSB address. You are advised to specify this parameter, which 
allows the return of block I/O status information and permits normal error reporting. 


The creation and function of the IOSB are described in detail in Section 2.9.2. 


bkdn 

Specifies the symbolic address of an optional asynchronous system trap (AST) service routine, 
which you code. If present, this parameter causes the AST service routine to be initiated at the 
specified address upon completion of block I/O; if not specified, no AST trap occurs. This parameter 
initializes File Descriptor Block (FDB) offset location F.BKDN. 


Considerations relevant to the use of an AST service routine are presented in Section 2.9.3. 


The following example shows an FDBK$A macro call that uses all available parameter fields for 
initializing the block access section of the FDB: 


FDBKSA BKBUF,240.,,20.,ISTAT,ASTADR 


In this macro call, the symbol BKBUF identifies a block I/O buffer reserved in your program 
that will accommodate a 24019-byte block. The virtual block number is null (for the reasons 
stated previously in the description of this parameter), and the event flag to be set upon block I/O 
completion is 20,9. Finally, the symbol ISTAT specifies the address of the IOSB, and the symbol 
ASTADR specifies the entry point address of the AST service routine. 

2.3.1.5 FDOP$A—Initialize File-Open Section of FDB 

The FDOP$A macro call initializes the file-open section of the FDB. In addition to a logical unit 
number (LUN), you would normally specify a data-set descriptor pointer, a default filename block 
address, or both, for each file that is to be opened. The latter two parameters provide FCS with 
the linkage necessary to retrieve file specifications from these data structures that you created in 
the program. 


Although both a data-set descriptor pointer (dspt) and the address of a default filename block 
(dfnb) may be specified for a given file, one or the other must be present in the FDB before that 
file can be opened. If, however, certain information is already present in the filename block as the 
result of prior program action, neither the data-set descriptor nor the default filename block is 
accessed by FCS, and you can open the file using a process called “opening a file by file ID.” This 
process, which is an efficient method of opening a file, is described in detail in Section 2.6. 


The dspt and dfnb parameters represent address values that point to data structures that you 
created in the program. These data structures, which are described in detail in Section 2.5, provide 
file specifications to the File Control Services (FCS) file-processing routines. 


FDOP$A __/un,dspt,dfnb,facc,actl 
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Parameter 


lun 

Specifies a numeric value that specifies a logical unit number (LUN). This parameter initializes 
FDB offset location FLUN. All I/O operations performed with this FDB are done through the 
specified LUN. Every active FDB must have a unique LUN. 


The LUN specified through this parameter may be any value from 1 through the largest value 
specified to the Task Builder through the UNITS option. This option specifies the number of logical 
units that the task is to use (see the JAS Task Builder Reference Manual.) 


dspt 

Specifies the symbolic address of a 6-word block in your task containing the data-set descriptor. 
This data structure, which you created, consists of a 2-word device descriptor, a 2-word directory 
descriptor, and a 2-word file name descriptor, as outlined in Section 2.5.1. 


The dspt parameter initializes FDB offset location F. DSPT. This address value, called the data-set 
descriptor pointer, is the linkage address through which FCS accesses the fields in the data-set 
descriptor. 


When the Command String Interpreter (CSI) processes command string input, a file specification 
is returned to the calling program in a format identical to that of the manually created data-set 
descriptor. The use of CSI as a dynamic command line processor is described in detail in Chapter 
6. 


dfnb 


Specifies the symbolic address of the default filename block. This structure is allocated within 
your task through the NMBLK¢$ macro call (see Section 2.5.2). When specified, the dfnb parameter 
initializes FDB offset location F.DFNB, allowing FCS to access the fields of the default filename 
block in building the filename block in the FDB. 


Specifying the dfnb parameter in the FDOP$A (or the FDOP$R) macro call assumes that the 
NMBLK$ macro call has been issued in the program. Furthermore, the symbol specified as the 
dfnb parameter in the FDOP$A (or the FDOP$R) macro call must correspond exactly to the symbol 
specified in the label field of the NMBLK$ macro call. 


facc 
Specifies any one, or any appropriate combination, of the following symbolic values indicating how 


the specified file is to be accessed: 

FO.RD Indicates that an existing file is to be opened for reading only. 

FO.WRT Indicates that a new file is to be created and opened for writing. 

FO.APD _ Indicates that an existing file is to be opened and appended. 

FO.MFY _ Indicates that an existing file is to be opened and modified. 

FO.UPD _ Indicates that an existing file is to be opened, updated, and, if necessary, extended. 


FA.NSP _ Indicates, in combination with FO.WRT, that an old file having the same file specification is not to be 
superseded by the new file. Rather, an error code is to be returned if a file of the same file name, type, 
and version exists. 


FA.TMP _ Indicates, in combination with FO.WRT, that the created file is to be a temporary file. 
FA.SHR _ Indicates that the file is to be opened for shared access. Shared access is also a precondition for block 
locking. 


The facc parameter initializes FDB offset location F. FACC. The symbolic values FO.xxx, described 
previously, represent the logical OR of bits in FDB location F.FACC. 


The information specified by this parameter can be overridden by an OPEN$ macro call, as 
described in Section 3.7. It is overridden by an OPEN$x macro call. 
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actl 
Specifies a symbolic value that specifies the following control information in FDB location F.ACTL: 


¢ Magnetic tape position. 


¢ Whether a disk file that is opened for write is to be locked if it is not properly closed; for 
example, the file may not be properly closed if the task terminates abnormally. 


¢ Number of retrieval pointers to allocate for a disk file window. 
¢ Whether to enable block locking. 


.Normally, FCS supplies default values for F.ACTL. However, if FA.ENB is specified in combination 
with any of the symbolic values described in the following text, FCS uses the information in 
F.ACTL. The FA.ENB location must be specified with the desired values to override the defaults. 
The following are the defaults for location F.ACTL: 


e For file creation, magnetic tapes are positioned to the end of the volume set. 
e §6At file open and close, tapes are not rewound. 
e A disk file that is opened for write is locked if it is not properly closed. 


¢ The volume default is used for the file window. 


The following values can be used with FA.ENB: 


FA.POS Is meaningful only for output files and is specified to cause a magnetic tape to be positioned 
just after the most recently closed file for creating a new file. Any files that exist after that 
point are lost. If rewind is specified, it takes precedence over FA.POS, thus causing the tape 
to be positioned just after the VOL1 label for file creation. See Chapter 5 for more information 
on tape positioning. 


FA.RWD Is specified to cause a magnetic tape to be rewound when the file is opened or closed. 
Examples of using FA.ENB with FA.POS and FA.RWD are provided in Chapter 5. 
FA.DLK Is specified to cause a disk file not to be locked if it is not properly closed. 


The number of retrieval pointers for a file window can be specified in the low-order byte of 
F.ACTL. The default number of retrieval pointers is the file-window mapping pointer count 
parameter (/WIN) included in the Monitor Console Routine (MCR) commands INI or MOUNT 
(DIGITAL Command Language (DCL) commands, INITIALIZE and MOUNT); the default value 
for this parameter is 7. Retrieval pointers point to contiguous blocks of the file on disk. Access 
to fragmented files may be optimized by increasing the number of retrieval pointers, that is, 
by increasing the size of the window. Similarly, because retrieval pointers use up pool space, 
additional memory can be freed up by reducing the number of pointers for files with little or no 
fragmentation—for example, contiguous files. 


FA.LKLIFA.EXL Is specified to lock all accessed blocks. FCS permits limited block locking to coordinate the 
access of the same file by two or more tasks. All tasks accessing the file must open the file 
for shared access by setting bit FA.SHR in FDB field F.FACC (the field access byte). 


See the [AS Device Handlers Reference Manual for further information on block locking. Also, 
see Section 2.9.4. 


As noted, if neither the dspt nor the dfnb parameter is specified, the corresponding offset locations 
F.DSPT and F.DFNB contain 0. In this case, no file is currently associated with this FDB. Any 
attempt to open a file with this FDB results in an open failure. Either offset location F.DSPT or 
F.DFNB must be initialized with an appropriate address value before a file can be opened using 
this FDB. Normally, these cells are initialized at assembly time through the FDOP$A macro call; 
but they may also be initialized at run time through the FDOP$R or the generalized OPEN$x 
macro call (see Chapter 3). 
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The examples at the end of this section show how the FDOP$A macro call may be used in your 
source program. 


Examples 
FDOPSA 1,,DFNB 


Indicates that the data-set descriptor pointer parameter (dspt) is null, requiring that FCS rely on 
the run-time specification of the data-set descriptor pointer for the FDB or the use of the default 
filename block for required file information. 


FDOPSA 2,OFDSPT 


Specifies a data-set descriptor pointer (named OFDSPT), which allows FCS to access the fields in 
the data-set descriptor for required file information. 


FDOPSA 2,OFDSPT, DFNB 


Specifies both a data-set descriptor pointer and a default filename block address, which causes 
FDB offset locations F. DSPT and F.DFNB, respectively, to be initialized with the appropriate 
values. In this case, FCS can access the data-set descriptor and the default filename block, or 
both, for required file information. By convention, FCS first seeks such information in the data-set 
descriptor; if all the required information is not present in this data structure, FCS attempts to 
obtain the missing information from the default filename block. 


FDOPSA 1,CSIBLK+C.DSDS 


Shows a macro call that takes as its second parameter a symbolic value that causes FDB offset 
location F.DSPT to be initialized with the address of the CSI data-set descriptor. This structure is 
created in the CSI control block by invoking the CSI$ macro call. All considerations relevant to th: 
use of CSI as a dynamic command line processor are presented in Chapter 6. 


FDOPSA 1,,DFNB,,FA.ENB!16. 


Shows the use of the act] parameter to increase the number of retrieval pointers in the file windov 
to 16. FA.ENB causes the contents of FACTL, rather than the defaults, to be used. 


In all the examples previously shown, the value specified as the first parameter supplies the logica 
unit number (LUN) used for all I/O operations involving the associated file. 


2.3.1.6 FDBF$A—Initialize Block Buffer Section of FDB | 
The FDBF$A macro call initializes the block buffer section of the FDB when record I/O operations 
(GET$ and PUT$ macro calls) process files. Initializing the FDB with this macro call allows FCS 
to control the necessary blocking and deblocking of individual records within a virtual block as an 
integral function of processing the file. 


FOBF$A_ efn,ovbs,mbct,mbfg 


efn 


Indicates a numeric value that specifies the event flag that FCS uses to synchronize record I/O 
operations. This numeric value initializes FDB offset location FEFN. FCS uses this event flag 
internally; you must not set, clear, or test it. 


If this parameter is not specified, FCS uses event flag 32;9. A null specification in this field is 
indicated by inserting a leading comma in the parameter string. 


ovbs 


Indicates a numeric value that specifies a file storage region (FSR) block buffer size, in bytes, that 
overrides the standard block size for the particular device associated with the file. This parametei 
initializes FDB offset location FOVBS with the specified block buffer size. 
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When you use ovbs to specify an FSR block buffer size for disks, specify the desired number 

of bytes in integral multiples of 51219 bytes, overriding the one-sector, standard 512 9-byte block 
buffer size. You can specify block buffer sizes up to 63 sectors (32,25619 bytes) for disks. Increasing 
the block buffer size in this manner greatly reduces average disk access time because several 
contiguous sectors are generally read or written during a typical disk access operation. An override 
block size of 20489 bytes (4 sectors) or 256019 bytes (5 sectors) is recommended because 2048 9 
bytes also provides American National Standards Institute (ANSI) magnetic tape buffer capability, 
and 256019 bytes is the Files-11 default extend size. Note that once the file has been opened, FCS 
uses the ovbs field for other purposes. Thus, if your task uses the FDB for additional disk I/O 
operations, the ovbs parameter must be issued in an FDBF$R macro prior to accessing the disk. 


NOTE: When you specify block buffer sizes greater than one sector (51219 bytes), you 
must increase accordingly the size of $$FSR1. This is done by specifying an appropriate 
value for the bufsiz parameter in the FSRSZ$ macro call (see Section 2.7.1). 


Routines that read ANSI-standard magnetic tape without prior knowledge of the format of the 
files to be read must specify an override block size of 8192)9 bytes. This value is sufficient for the 
largest ANSI-standard tape blocks. 


Issuing the CLOSE$ macro call (see Chapter 3) resets offset location F.OVBS in the associated 
FDB to 0. Therefore, this location should typically be initialized at run time, just before opening 
the file, particularly if an OPEN$x/CLOSE$ sequence for the file is performed more than once. 


On certain devices, such as line printers and terminals, the block size should not exceed the 
device’s line width. The task can obtain the proper block size for these devices by issuing the 

Get LUN Information system directive for each device. (See the description for the Get LUN 
Information directive in the IAS Executive Facilities Reference Manual. The standard block size for 
each device is established at system generation time or by the MCR command SET/BUF. 


mbct 


Indicates a numeric value that specifies the multiple buffer count, that is, the number of buffers 
FCS uses in processing the associated file. This parameter initializes FDB offset location F.MBCT. 
If this value is greater than 1, multibuffering is effectively declared for file processing. In this case, 
FCS employs either read-ahead or write-behind operations, depending on which of two symbolic 
values is specified as the mbfg parameter (see the following entry). 


If the mbct parameter is specified as null or 0, FCS uses the default buffer count contained in 
symbolic location A.DFBC in $$FSR2 (the program section in the FSR containing impure data). 
This cell normally contains a default buffer count of 1. If desired, this value can be modified, as 
noted in the discussion of the mbfg parameter in the following entry. — 


If, in specifying the FSRSZ$ macro call (see Section 2.7.1), sufficient memory space has not been 

allocated to accommodate the number of buffers established by the mbct parameter, FCS allocates 
as many buffers as can fit in the available space. Insufficient space for at least one buffer causes 
FCS to return an error code to FDB offset location F. ERR. 


You can initialize the buffer count in F MBCT through either the FDBF$A or the FDBF$R macro 
call. The buffer count so established is not altered by FCS and, once set, need not be of further 
concern to you. 


When input is from record devices (for example, a card reader), F. MBCT should not be greater than 
2. 


mbtg 


Specifies a symbolic value that specifies the type of multibuffering to be employed in processing the 
file. Either of the following two values may be specified to initialize FDB offset location F.MBFG: 


FD.RAH _ Indicates that read-ahead operations are to be used in processing the file 
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FD.WBH _ssiIndicates that write-behind operations are to be used in processing the file 
These parameters are mutually exclusive; that is, one or the other, but not both, may be specified. 


Specifying this parameter assumes that the buffer count established in the mbct parameter 
shown previously is greater than 1. If multibuffering has thus been declared, omitting the mbfg 
parameter causes FCS to use read-ahead operations by default for all files opened using the 
OPEN$R macro call; similarly, FCS uses write-behind operations by default for all files opened 
using other forms of the OPEN$x macro call. 


If these default buffering conventions are not desired, you can alter the value in the F MBFG 
dynamically at run time. This is done by issuing the FDBF$R macro call, which takes as the mbfg 
parameter the appropriate control flag (FD.RAH or FD.WBH). This action must be taken, however, 
before opening the file. 


Offset location F MBFG in the FDB is reset to 0 each time the associated file is closed. 


NOTE: When using write-behind multibuffering, there is no gain in efficiency if the size 
of the file must be increased to make room for the data to be written. If a file is being 
written at the end, using default extension, there will be one extend operation for each 
five write operations; thus, only 80% of the write-behind operations will actually be 
overlapped with processing. This percentage can be increased as follows: 


¢ To preallocate space for the file completely, use either the cnig parameter in the 
FDAT$A macro or the .EXTND subroutine. 


e To increase the default extension amount from five blocks, use the aloc parameter 
of the FDAT$A macro call. For example, if you specify an aloc parameter of 10)0, the 
number of write-behind operations that will be overlapped increases to 90%. 


e You can access the file by using random I/O. Because issuing PUT$R macros 
to access random preexisting locations in the file does not require extends, the 
percentage of overlapped operations is increased. 


You can change the default buffer count, if desired, by modifying a location in $$FSR2, which is 
the second of two program sections comprising the FSR. A location defined as .MBFCT in $$FSR2 
normally contains a default buffer count of 1. This default value may be changed, as follows: 


¢ Apply a global patch to A.DFBC at task-build time to specify the desired number of buffers. 


¢ For MACRO-11 programs, use the EXTSCT option of the Task Builder (see Section 2.8.1) to 
allocate more space for the FSR block buffers; for FORTRAN programs, use the ACTFIL option 
of the Task Builder (see Section 2.8.2) to allocate more space for the FSR block buffers. 


Because the previous procedure alters the default buffer count for all files to be processed by your 
program, it may be desirable to force single buffering for any specific file or files that would not 
benefit from multibuffering. In such a case, you can set the buffer count in F MBCT for a specific 
file to 1 by issuing the following example macro call for the applicable FDB: 


FDBFSA ,,1 


The value 1 specifies the buffer count (mbct) for the desired file and is entered into offset location 
F.MBCT in the applicable FDB. Note in the previous example that the event flag (efn) and the 
override block buffer size (ovbs) parameters are null; these null values are for illustrative purposes 
only and should not be interpreted as conditional specifications for establishing single-buffered 
operations. 


The following examples show how the FDBF$A macro call may be used in a program. 
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Examples 
FDBFSA 25.,,1 


Specifies that event flag 2519 synchronizes record I/O operations and that single buffering is used 
in processing the file. 


FDBFSA 25.,,2,FD.RAH 


Specifies event flag 25,9 for synchronizing record I/O operations and, in addition, establishes 2 as 
the multiple buffer count. The buffers so specified are for read-ahead operations, as indicated by 
the final parameter. 


FDBFSA 1,2,FD.WBH 


Allows event flag 3219 to be used by default for synchronizing record I/O operations, and the two 
buffers specified in this case are for write-behind operations. 


Note in all three examples that the second parameter, that is, the override block size parameter 
(ovbs), is null; thus, the standard block size in effect for the device in question is used for all file 
1/O operations. 


Run-Time FDB Initialization Macros 


Although the FDB is allocated and can be initialized during program assembly, the contents of 
specific sections of the FDB can also be initialized or changed at run time by issuing any of the 
following macro calls: 

FDAT$R Initializes or alters the file attribute section of the FDB. 

FDRC$R Initializes or alters the record access section of the FDB. 

FDBK$R Initializes or alters the block access section of the FDB (see item 4 in Section 2.3.2.1 following). 
FDOP$R Initializes or alters the file-open section of the FDB. 

FDBF$R Initializes or alters the block buffer section of the FDB. 

There are no default values for run-time FDB macros (except for the FDB address). At run time, 
the values currently in the FDB are used unless they are explicitly overridden. For example, 


values stored in the FDB at assembly time are used at run time unless they are overridden. The 
run-time FDB macros place the FDB address in RO. 


2.3.2.1 Run-Time FDB Macro Exceptions 
The format and the parameters of the run-time FDB initialization macros are identical to the 
assembly-time macros described earlier, except as noted here: 


e An R rather than an A must appear as the last character in the run-time symbolic macro 
name. 


e ©The first parameter in all run-time macro calls must be the address of the FDB associated with 
the file to be processed. All other parameters in the run-time macro calls are identical to those 
described in Sections 2.3.1.2 to 2.3.1.6 for the assembly-time macro calls, except as noted in 
items 3 and 4 in this section. 


¢ The parameters in the run-time macro calls must be valid MACRO-11 source operand 
expressions. These parameters may be address values or literal values; they may also 
represent the contents of registers or memory locations. In short, any value that is a valid 


2-17 


Preparing for I/O 


source operand in a MOV or MOVB instruction may be specified in a run-time macro call. In 
this regard, the following conventions apply: 


— Ifthe parameter is an address value or a literal value that is to be placed in the FDB, that 
is, if the parameter itself is to be taken as an argument, it must be preceded by the number 
sign (#). This symbol is the immediate expression indicator for MACRO-11 programs, 
causing the associated argument to be taken literally in initializing the appropriate cell in 
the FDB. Such literal values may be specified as follows: 


FDOPSR #FDBADR, #1, #DSPT, #DFNB 


— Ifthe parameter is the address of a location containing an argument that is to be placed in 
the FDB, the parameter must not be preceded by the number sign. Such a parameter may 
be specified as follows: 


ONE: - WORD 1 


FDOPSR #FDBADR, ONE, #DSPT, #DFNB 
ONE represents the symbolic address of a location containing the desired initializing value. 


— Ifthe parameter is a register specifier (for example, R4), the parameter must not be 
preceded by the number sign. Register specifiers are defined MACRO-11 symbols and are 
valid expressions in any context. 


NOTE: RO can only be specified in the first parameter (FDB address). Any other 
use of RO will fail. (See Section 2.3.2.2.) 


Thus, in contrast, parameters specified in assembly-time macro calls are used as arguments in 
generating data in .WORD or .BYTE directives, while parameters specified in run-time macro 
calls are used as arguments in MOV and MOVB machine instructions. 


¢ As noted in the description of the FDBK$A macro call in Section 2.3.1.4, assembly-time 
initialization of the FDB with the virtual block number is meaningless because issuing the 
OPEN$x macro call to prepare a file for processing resets the virtual block number in the FDB 
to 1. For this reason, the virtual block number can be specified only at run time after the 
file has been opened. Do this by issuing either the FDBK$R macro call or the I/O-initiating 
READ$ or WRITE$ macro call. In all three cases, the relevant field for defining the virtual 
block number is the bkvb parameter. The READ$ and WRITE$ macro calls are described in 
detail in Chapter 3. 


At assembly time, you must reserve and label a 2-word block in the program to temporarily 
store the virtual block number appropriate for intended block I/O operations. Because your 
task is free to manipulate the contents of these two locations at will, any virtual block number 
consistent with intended block I/O operations may be defined. By specifying the symbolic 
address (that is, the label) of this field as the bkvb parameter in the selected run-time macro 
call, you can make the virtual block number available to FCS. 


In preparing for block I/O operations, you must follow these procedures: 


1 At assembly time, reserve a 2-word block in your program through a statement that is 
logically equivalent to the following: 


VBNADR: .BLKW 2 


The label VBNADR names this 2-word block and defines its address. This symbol is used 
subsequently as the bkvb parameter in the selected run-time macro call for initializing the 
FDB. 
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2 Atrun time, load this field with the desired virtual block number. This operation may be 
accomplished through statements logically equivalent to the following: 


CLR VBNADR 
MOV #10400, VBNADR+2 


Note that the first word of the block is cleared. The MOV instruction then loads the second 
(low-order) word of the block with a numeric value. This value constitutes the 16 least 
significant bits of the virtual block number. 


If the desired virtual block number cannot be completely expressed within 16 bits, the 
remaining portion of the virtual block number must be stored in the first (high-order) word 
of the block. This may be accomplished through statements logically equivalent to the 
following: 


MOV #1, VBNADR 
MOV #10400, VBNADR+2 


As a result of these two instructions, 31 bits of value are defined in this 2-word block. The 
first word contains the 15 most significant bits of the virtual block number, and the second 
word contains the 16 least significant bits. Thus, the virtual block number is an unsigned 
value having 31 bits of magnitude. You must ensure that the sign bit in the high-order 
word is not set. 


3 Open the desired file for processing by issuing the appropriate version of the generalized 
OPEN$x macro call (see Chapter 3). 


4 Issue either the FDBK$R macro call or the READ$ or WRITE$ macro call, as appropriate, 
to initialize the relevant FDB with the desired virtual block number. 


If the FDBK$R macro call is elected, the following is a representative example: 
FDBK$R #FDBIN,,,#VBNADR 


Regardless of the particular macro call that supplies the virtual block number, the two 
words at VBNADR are loaded into F BKVB and F. BKVB+2. The first of these words 
(F.BKVB) is 0 if 16 bits are sufficient to express the desired virtual block number. The 
I/O-initiating READ$ or WRITE$ macro call may then be issued. 


Should you choose, however, to initialize the FDB directly through either the READ$ or 
WRITE$ macro call, the virtual block number may be made available to FCS through a 
statement such as the following: 


READS #FDBIN, #INBUF, #BUFSIZ, #VBNADR 


The symbol VBNADR represents the address of the 2-word block in your program 
containing the virtual block number. 


2.3.2.2 Specifying the FDB Address in Run-Time Macros 
In relation to the second item of exceptions noted previously, the address of the File Descriptor 
Block (FDB) associated with the file to be processed corresponds to the address value of the symbol 
that you defined appearing in the label field of the FDBDF$ macro call (see Section 2.3.1.1). For 
example, the following statement not only allocates space for an FDB at assembly time, but it also 
binds the label FDBOUT to the beginning address of the FDB associated with this file: 


FDBOUT: FDBDFS$ 
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The address value so established can then be specified as the initial parameter in a run-time macro 
call in any one of the following three ways: 


1 The address of the appropriate FDB may be specified as an explicit parameter in a run-time 
macro call, as indicated in the following example statement: 


FDATSR #FDBOUT, #R.VAR, #FD.CR 


The argument FDBOUT is taken literally by File Control Services (FCS) as the address of 
an FDB; furthermore, this address value, by convention, is stored in general register 0 (RO). 
Whenever this method of specifying the FDB address is employed, the previous contents of RO 
are overwritten (and thus destroyed). Therefore, you must exercise care in issuing subsequent 
run-time macro calls to ensure that the present value of RO is suitable to current purposes. 


2 You may use a general register specifier as the initial parameter in a run-time macro call. 
When you use a register other than RO, the contents of the specified register are moved to RO. 
The previous contents of RO are overwritten (and thus destroyed). 


The following statement reflects the use of a general register to specify the FDB address: 
FDATSR RO, #R.VAR, #FD.CR 


In this case, the current contents of RO are taken by FCS as the address of the appropriate 
FDB. This method assumes that the address of the FDB has been previously loaded into RO 
through some overt action. Note, when using this method to specify the FDB address, that the 
immediate expression indicator (#) must not precede the register specifier (RO). 


3 A null specification may be used as the initial parameter in a run-time macro call, as shown in 
the following statement: 


FDATSR ,#R.VAR, #FD.CR 


In this case, the current contents of RO are taken by default as the address of the associated 
FDB. As shown previously, RO is assumed to contain the address of the desired FDB. Although 
the comma in this instance constitutes a valid specification, you are advised to employ methods 
1 and 2 for consistency and clarity of purpose. 


These three methods of specifying the FDB address also apply to all the FCS file-processing macro 
calls described in Chapter 3. 


Global Versus Local Definitions for FDB Offsets 


Although the FDB offsets can be defined either locally or globally, the design of FCS does not 
require that you be concerned with the definition of FDB offsets locally. To some extent, this design 
consideration is based on the manner in which MACRO-11 handles symbols. 


Whenever a symbol appears in the source program, MACRO-11 assumes that it is a global symbol 
unless it is presently defined within the current assembly. Such a symbol must be defined further 
on in the program; otherwise, it will be treated by MACRO-11 as a default global reference, 
requiring that it be resolved by the Task Builder. 


Thus, the question of global versus local symbols may simply be a matter of the programmer’s not 
defining the FDB offsets and bit values locally in coding the program. Such undefined symbols 
thus become global references, which are reduced to absolute definitions at task-build time. 


It should be noted that global symbols may be used as operands and macro-call parameters, or 
both, anywhere in the source program coding, as described in the following section. 
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Specifying Global Symbols in the Source Code 


Throughout the descriptions of the assembly-time macros (see Sections 2.3.1.2 to 2.3.1.6), global 
symbols are specified as parameters in the macro calls. As noted earlier, such symbols are treated 
by MACRO-11 as default global references. 


For example, the global symbol FD.RAN may be specified as the initial parameter in the FDRC$A 
macro call (see Section 2.3.1.3). At task-build time, this parameter is reduced to an absolute 
symbol definition, causing a prescribed bit to be set in the record access byte (offset location 
F.RACC) of the FDB. 


Global symbols may also be used as operands in your task’s instructions to accomplish operations 
associated with FDB offset locations. For example, global offsets such as FRACC, F.RSIZ, and 
F.RTYP may be specified as operands in the source coding. Assume, for example, that an FDBDF$ 
macro call (see Section 2.3.1.1) has been issued in the source program to allocate space for an FDB, 
as follows: 


FDBIN: FDBDFS$ 


The coding sequence shown in the following text may then appear in the source program, 
illustrating the use of the global offset F.RACC: 


MOV 4FDBIN, RO 
MOVB #FD.RAN, F.RACC (RO) 


Note that the beginning address of the FDB is first moved into general register zero (RO). However, 
if the desired value already exists in RO as the result of previous action in the program, you need 
issue only the second MOV instruction (which appropriately references RO). As a consequence of 
this instruction, the value FD.RAN initializes FDB offset location F.RACC. 


The following statement is an equivalent instruction, which similarly initializes offset location 
F.RACC in the FDB with the value of FD.RAN: 


MOVB #FD.RAN, FDBIN+F .RACC 


Global symbols may be used anywhere in the program in this manner to effect the dynamic storage 
of values within the FDB. 


Defining FDB Offsets and Bit Values Locally 


If you want your task to declare explicitly that all FDB offsets and bit values are to be defined 
locally, there are two macro calls in the source program you can invoke. The first of these, 
FDOF$L, causes the offsets for FDBs to be defined within your program. Similarly, bit values 

for all FDB parameters may be defined locally by invoking the FCSBT$ macro call. You can invoke 
these macro calls anywhere in your program. 


When issued, the FDOF$L and FCSBT$ macro calls define symbols in a manner roughly equivalent 
to the following: 


F.RTYP = xxxx 
F.RACC = xxxx 
F.RSIZ = xxxx 
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Parameter 


XXXX 
Represents the value assigned to the corresponding symbol. 


In other words, the macros for defining FDB offsets and bit values locally do not generate any code 
Their function is simply to create absolute symbol definitions within the program at assembly time 
The symbols so defined, however, appear in the MACRO-11 symbol table, rather than in the source 
program listing. Such local symbol definitions are thereby made available to MACRO-11 during 
assembly, rather than forcing them to be resolved by the Task Builder. 


Whether the FDOF$L and FCSBT$ macros are invoked should not in any way affect the coding 
style or the manner in which the FDB offsets and bit values are used. 


Note, however, that if the FDOF$L macro is issued, the NBOF$L macro for the local definition 
of the filename block need not be issued (see Section 2.5.2). The FDOF$L macro defines all FDB 
offsets locally, including those for the filename block. 


If any of the previously named macros is to be issued in your program, it must first be listed as an 
argument in a .MCALL directive (see Section 2.2). 


Creating File Specifications Within Your Program 


Certain information describing the file must be present in the FDB before the file can be opened. 
The file is located using a file specification that contains the following: 


e A device name and unit number. 


e A directory string consisting of a group number and a member number that specify the User 
File Directory (UFD) to be used for the file. The term “UFD” is synonymous with the term “file 
directory string,” which appears throughout this manual. 


e 6A file name. 
¢ A file type. 


° A file version number. 


A file specification describing the file to be processed is communicated to FCS through the following 
two data structures that you create: 


¢ The data-set descriptor. This tabular structure may be created and initialized manually 
through the use of .WORD directives. Section 2.5.1 describes this data structure in detail. 


¢ The default filename block. In contrast to the manually created data-set descriptor, the default 
filename block is created by issuing the NMBLK$ macro call. This macro call allocates a block 
of storage in your program at assembly time and initializes this structure with parameters 
supplied in the call. This structure is described in detail in Section 2.5.2. 


As noted in Section 2.3.1.5, the FDOP$A or the FDOP$R macro call is issued to initialize the FDB 
with the addresses of these data structures. These address values are supplied to FCS through the 
dspt and dfnb parameters of the selected macro call. FCS uses these addresses to access the fields 
of the data-set descriptor and the default filename block, or both, for the file specification required 
in opening a specified file. 


By convention, a required file specification is first sought by FCS in the data-set descriptor. 
Any nonnull data contained therein is translated from American Standard Code for Information 
Interchange (ASCII) to Radix-50 format and is stored in the appropriate offsets of the filename 
block. This area of the FDB then serves as the execution time repository for the information 
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describing the file to be opened and processed. If the data-set descriptor does not contain the 
required information, FCS attempts to obtain the missing information from the default filename 
block. If neither of these structures contains the required information, an open failure occurs. 


Note, however, that the device name and the unit number need not be specified in either the 
data-set descriptor or the default filename block, because these values are defaulted to the device 
and unit assigned to the logical unit number (LUN) at task-build time if not explicitly specified. 


The FCS file-processing macro calls used in opening files are described in Chapter 3, beginning 
with the generalized OPEN$x macro call. 


For a detailed description of the format and content of the filename block, refer to Appendix B. 


Data-Set Descriptor 


The data-set descriptor is often oriented toward the use of a fixed (built-in) file name in your 
program. A given application program, for example, may require access only to a limited and 
nonvariable number of files throughout its execution. By defining the names of these files at 
assembly time through the data-set descriptor mechanism, such a program, once initiated, executes 
to completion without requiring additional file specifications. 


This structure, a 6-word block of storage that you can create manually within your program by 
using .WORD directives, contains information describing a file that you intend to open during 
the course of program execution. In creating this structure, you can define any one or all of three 
possible string descriptors for a particular file, as follows: 


¢ A two-word descriptor for an ASCII device name string. To allocate this data structure, use the 
following format: 
WORD Contains the length (in bytes) of the ASCII device name string. 
1 


This string consists of a two-character alphabetic device name, followed by an optional octal 
unit number and an optional colon or a logical name. You can create these strings by issuing 
statements such as the following: 


DEVNM: .ASCII /DUO:/ 


DEVNM: .ASCII /TT10:/ 


WORD Contains the address of the ASCII device name string. 
2 


-© A two-word descriptor for an ASCII file directory string. To allocate this data structure, use 


the following format: 


WORD Contains the length (in bytes) of the ASCIl file directory string. 


3 This string consists of a group number and a member number, separated by a comma (, ). 


The entire string is enclosed in brackets. For example, [200,200] is a directory string. You can 
create a directory string by issuing statements such as the following: 


DIRNM: .ASCII /[200,200]/ 


DIRNM: .ASCII /[40,100]/ 


If you want your task to specify an explicit file directory different from the UFD under which 
you are currently running, the data-set descriptor mechanism permits that flexibility. 


WORD Contains the address of the ASCII file directory string. 
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¢ A two-word descriptor for an ASCII filename string. To allocate this data structure, use the 
following format: 


WORD Contains the length (in bytes) of the ASCII filename string. 


5 This string contains the following: 


¢ A filename up to nine characters in length. 

* An optional three-character file type designator. 

* An optional file version number. 

The filename and file type must be separated by a period (.), and the file version number 


must be preceded by a semicolon. A filename string can be created as shown in the following 
statement: 


FILNM: .ASCII /PROG1.OBJ;7/ 


For FILES-11, only the characters A to Z and 0 to 9 can be used in an ASCII filename 
string. In addition, an ANSI magnetic tape filename string can contain the following special 
characters: 


SPI"%&'()*+,-./ij;< =>? 
A name that contains any of these characters must be enclosed in quotation marks (""). If 


a quotation mark is part of the name, the string must contain two quotation marks. An ANSI 
filename string can be created as shown in the following example: 


FILNM: .ASCII /"PROG""2"";%&;";7/ 
The filename created in the previous example is as follows: 


PROG"2"; $&; 77 


NOTE: The semicolon is a legal character in the name string. To delimit 
a version number, the semicolon must be outside the quoted string. 


WORD Contains the address of the ASCII filename string. 
6 


A length specification of 0 in Word 1, 3, or 5 of the data-set descriptor indicates that the 
corresponding device name, directory, or filename string is not present in your program. For 
example, the following code creates a data-set descriptor containing only a 2-word ASCII filename 
string descriptor: 


FDBOUT: FDBDFS$ 7CREATES FDB. 
FDATSA R.VAR,FD.CR ; INITIALIZES FILE-ATTRIBUTE SECTION. 
FDRCSA_ ,RECBUF, 80. ;INITIALIZES RECORD-ACCESS SECTION. 


FDOPSA OUTLUN,OFDSPT ; INITIALIZES FILE-OPEN SECTION. 


OFDSPT: .WORD 0,0 7NULL DEVICE-NAME DESCRIPTOR. 
«WORD 0,0 7;NULL DIRECTORY DESCRIPTOR. 
- WORD ONAMSZ , ONAM 7;FILENAME DESCRIPTOR. 


ONAM: -ASCII /OUTPUT.DAT/ ;DEFINES FILENAME STRING. 
ONAMSZ=.-ONAM 7;DEFINES LENGTH OF FILENAME STRING. 
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Note first that an FDB labeled FDBOUT is created. Observe further that the FDOP$A macro 
call takes as its second parameter the symbol OFDSPT. This symbol represents the address value 
stored in FDB offset location F.DSPT. This value enables the .PARSE routine (see Chapter 4) to 
access the fields of the data-set descriptor in building the filename block. 


The symbol OFDSPT also appears in the label field of the first .WORD directive, defining the 
address of the data-set descriptor for the .PARSE routine. The .WORD directives each allocate 
two words of storage for the device name descriptor, the file directory descriptor, and the filename 
descriptor, respectively. 


In the preceding example, however, note that the first two descriptor fields are filled with zeros, 


‘indicating null specifications. The last .WORD directive allocates two words that contain the size 


and the address of the filename string, respectively. The filename string itself is explicitly defined 
in the .ASCII directive that follows. 


Note that the statements defining the filename string need not be physically contiguous to the 
data-set descriptor. For each such ASCII string referenced in the data-set descriptor, however, 
corresponding statements must appear elsewhere in the source program to define the appropriate 
ASCII data string or data strings. 


A data-set descriptor for each of several files to be accessed by your program can be defined in this 
manner. 


Default Filename Block—NMBLK$ Macro 


As noted earlier, you can also define a default filename block in the program as a means of 
providing required file information to File Control Services (FCS). For this purpose, you can 
issue the NMBLK$ macro call in connection with each FDB for which a default filename block is to 
be defined. When this macro call is issued, space is allocated within your program for the default 
filename block, and the appropriate locations within this data structure are initialized according to 
the parameters supplied in the call. 


Note in the parameter descriptions in the following text that symbols of the form N.xxxx are used 
to represent the offset locations within the filename block. These symbols are differentiated from 
those that apply to the other sections of the FDB by the beginning character N. All versions of the 
generalized OPEN$x macro call (see Chapter 3) use these symbols to identify offsets in storing file 
information in the filename block. 


label: NMBLK$ fnam, ftyp, fver,dvnm,unit 


Parameters 


label 

Specifies a symbol, which you define, that names the default filename block and defines its address. 
This label is the symbolic value normally specified as the dfnb parameter when the FDOP$A or the 
FDOP$R macro call is issued. This causes FDB offset location F.DFNB to be initialized with the 
address of the default filename block. 


fnam 


Specifies the default filename. This parameter can consist of up to nine ASCII characters. The 
character string is stored as 6 bytes in Radix-50 format, starting at offset location N.FNAM of the 
default filename block. 
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ftyp 

Specifies the default file type. This parameter can consist of up to three ASCII characters. The 
character string is stored as 2 bytes in Radix-50 format in offset location N.FTYP of the default 
filename block. 


fver 

Specifies the default file version number (binary). When specified, this binary value identifies a 
particular version of a file. This value is stored in offset location N.FVER of the default filename 
block. 


dvnm 


Specifies the default name of the device upon which the volume containing the desired file is 
mounted. This parameter consists of two ASCII characters that are stored in offset location 
N.DVNM of the default filename block. 


unit 

Specifies a binary value identifying which unit (among several like units) is to be used in 
processing the file. If specified, this numeric value is stored in offset location N.UNIT of the 
default filename block. 


Only the alphanumeric characters A to Z and 0 to 9 can be used in composing the filename and file 
type strings discussed previously. Although the file version number and the unit number discussed 
previously are binary values, these numbers are normally represented in octal form when printed, 
when input by a command string, or when supplied through a data-set descriptor string. 


As evident from the preceding text, all the default information supplied in the NMBLK$ macro call 
is stored in the default filename block at offset locations that correspond to identical fields in the 
filename block within the FDB. This default information is moved into the corresponding offsets of 
the filename block when any version of the generalized OPEN$x macro call is issued under any of 
the following conditions: 


e¢ All the file information required by FCS to open the file is not present in the data-set 
descriptor. Missing information is then sought in the default filename block by the .PARSE 
routine (see Chapter 4), which is invoked as a result of issuing any version of the generalized 
OPEN$x macro call. 


¢ A data-set descriptor has not been created in your program. 


e A data-set descriptor is present in your program, but the address of this structure has not been 
made available to FCS through any of the assembly-time or run-time macro calls that initialize 
FDB offset location F.DSPT. 


The following code illustrates the general method of specifying the NMBLK$ macro call: 


FDBOUT: FDBDFS$ 7;ALLOCATES SPACE FOR AN FDB. 
FDATSA R.VAR,FD.CR ; INITIALIZES FILE-ATTRIBUTE SECTION. 
FDRCSA ,RECBUF, 80. 7; INITIALIZES RECORD-ACCESS SECTION. 
FDOPSA OUTLUN, , OFNAM ; INITIALIZES FILE-OPEN SECTION. 

FDBIN: FDBDFS 7; ALLOCATES SPACE FOR AN FDB. 
FDRCSA_ ,RECBUF, 80. 7; INITIALIZES RECORD-ATTRIBUTE SECTION. 
FDOPSA INLUN, , IFNAM 7; INITIALIZES FILE-OPEN SECTION. 

OFNAM: NMBLKS OUTPUT,DAT 7;ESTABLISHES filename AND FILE TYPE. 


IFNAM: NMBLKS INPUT,DAT,,DT,1 ;ESTABLISHES filename, FILE TYPE, 
;DEVICE NAME, AND UNIT NUMBER. 
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The first NMBLK$ macro call in the previous coding sequence creates a default filename block to 
establish default information for the FDB, named FDBOUT. The label OFNAM in this macro 
defines the beginning address of the default filename block allocated within your program. 

Note that this symbol is specified as the dfnb parameter in the FDOP$A macro call associated 
with this default filename block to initialize the file open section of the corresponding FDB. The 
accompanying parameters in the first NMBLK$ macro call define the filename and the file type, 
respectively, of the file to be opened; all remaining parameter fields in this call are null. 


The second NMBLK$ macro call accomplishes essentially the same operations in connection with 
the FDB, named FDBIN. Note in this macro call that the third parameter (the file version number) 
is null, as reflected by the extra comma. This null specification indicates that the latest version 
of the file is desired. All other parameter fields contain explicit declarations defining default 
information for the applicable FDB. 


You can define the offsets for a filename block locally in your program by issuing the following 
macro call: 


NBOFSL 


This macro call does not generate any code. Its function is merely to define the filename block 
offsets locally, presumably to conserve symbol table space at task-build time. The NBOF$L macro 
call need not be issued if the FDOF$L macro call has been invoked because the filename block 
offsets are defined locally as a result of issuing the FDOF$L macro call. 


If you want, you can initialize fields in the default filename block directly with appropriate values. 
You can do this by placing inline statements in the program. For example, a specific offset in the 
default filename block can be initialized through coding that is logically equivalent to the following 
coding: 


DFNB: NMBLK$ IASLIB, OBJ 
NUTYP: .RAD50 /DAT/ 


MOV NUTYP , DFNB+N.FTYP 


The symbol NUTYP in the MOV instruction represents the address of the newly defined Radix-50 
file type DAT, which is to be moved into destination offset N.FTYP of the default filename block 
labeled DFNB. 


You can manually initialize any of the offsets within the default filename block in this manner to 
establish desired values or to override previously initialized values. 


Note 


The NMBLK$ macro cannot be used to create a filename containing non-Radix-50 characters or a 
filename that is not in the normal filenam.typ format. A program that uses the filename format 
permitted for ANSI magnetic tape must set up the filename in a data-set descriptor. 
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Dynamic Processing of File Specifications 


If you want your task to make use of routines available from the system object library 
([1,1JSYSLIB.OLB) for processing command line input dynamically, consult Chapter 6. Chapter 
6 describes the Get Command Line (GCML) routine and the Command String Interpreter (CSI) 
routine, both of which can be linked with your program to provide all the logical capabilities 
required in processing dynamic terminal input or indirect command file input. 


Optimizing File Access 


When certain information is present in the filename block beginning at the symbolic F.FNB of an 
File Descriptor Block (FDB), a file can be opened in a manner referred to throughout this manual 
as “opening a file by file ID.” This type of open requires a minimum of system overhead, resulting 
in a significant increase in the speed of preparing a file for access by your program. If files are 
frequently opened and closed during program execution, opening files by file ID accomplishes 
substantial savings in overall execution time. 


To open a file by file ID, the minimum information that must be present in the filename block of 
the associated FDB consists of the following: 


File identification field A 3-word field beginning at the filename block offset location N.FID that 
contains a file number in the first word and a file sequence number in 
the second word; the third word is reserved. The file identification field is 
maintained by the system and ordinarily need not be of concern to you. 

Device name field A 1-word field at the filename block offset location N.DVNM that contains 
the 2-character ASCII name of the device on which the volume containing 
the desired file is mounted. 

Unit number field A 1-word field at the filename block offset location N.UNIT that contains 
a binary value identifying the particular unit (among several like units) on 
which the volume containing the desired file is mounted. 


These three fields are written into the filename block in one of the following three ways: 


e By issuing any version of the generalized OPEN$x macro call for a file associated with the FDB 
in question 

¢ §=6By initializing the filename block manually by using the .PARSE routine and the .FIND routine 
(see Chapter 4) 


¢ By moving the necessary values into the filename block 


Initializing the Filename Block as a Function of OPEN$x 


To understand how to effect the process of opening a file by file ID, note that the initial issuance 
of the generalized OPEN$x macro call (see Chapter 3) for a given file first invokes the .PARSE 
routine (see Chapter 4). The PARSE routine is linked into your program, along with the code for 
OPEN$x. This routine first zeros the filename block and then fills it in with information taken 
from the data-set descriptor and the default filename block. 


Thus, issuing the generalized OPEN$x macro call invokes the .PARSE routine each time a file is 
opened. The .PARSE function, however, can be bypassed altogether in subsequent OPEN$x calls 
by saving and restoring the filename block before attempting to reopen that same file. 
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This is made possible because of the logic of the OPEN$x macro call. Specifically, after the initial 
OPEN$x for a file has been completed, the necessary context for reopening that file exists within 

the filename block. Therefore, before closing that file, the entire filename block can be copied into 
your task’s memory space and later restored to the FDB at the desired point in program flow for 

use in reopening that same file. 


Your task can reopen files in this manner because FCS is sensitive to the presence of any nonzero 
value in the first word of the file identification field of the filename block. When your task invokes 
the OPEN$x function, FCS first examines offset location N.FID of the filename block. If the first 
word of this field contains a value other than 0, FCS logically assumes that the remaining context 
necessary for opening that file is present in the filename block, and therefore unconditionally opens 
that file by file ID. 


To ensure that an undesired value does not remain in the first word of the N.FID field from a 
previous OPEN$x or CLOSE$ sequence, the first word of this field is zeroed as the file is closed. 


In opening files by file ID, you need only ensure that manual saving and restoring of the filename 
block are accomplished with inline MOV instructions that are consistent with the desired sequence 
of processing files. This process should proceed as follows: 


1 Open the file in the usual manner by issuing the OPEN$x macro call. 


2 Save the filename block by copying it into your task’s memory space with appropriate MOV 
instructions. The filename block begins at offset location F.FNB in the FDB. 


The value of the symbol S.FNB is the size of the filename block in bytes, and the value of the 
symbol S.FNBW is the size of the filename block in words. If desired, the NBOF$L macro 
call (see Section 2.5.2) can be invoked in your program to define these symbols locally. These 
symbolic values can be used in appropriate MOV instructions to accomplish the saving and 
restoring of the filename block. Moreover, you must reserve sufficient space in the program for 
saving the filename block. 


3 At the end of current file operations, close the file in the usual manner by issuing the CLOSE$ 
macro call. 


4 When, in the normal flow of program logic, that same file is about to be reopened, restore the 
filename block to the FDB by reversing step 2. 


5 Reopen the file by issuing any one of the macro calls available in FCS for opening an existing 
file. Because the first word of offset location N.FID of the filename block now contains a 
nonzero value, FCS unconditionally opens the file by file ID, regardless of the specific type of 
open macro call issued. 


Although you must save only the file identification, device name, and unit number fields of the 
filename block in anticipation of reopening a file by file ID, you are advised to save the entire 
filename block. The filename, file type, file version, and directory-ID fields, and so forth, might also 
be relevant. For example, an OPEN$x, save, CLOSE$, restore, OPEN$x, and DELET$ sequence 
would require saving and restoring the entire filename block. 


Though you might be logically finished with file processing and might want to delete the file, 
the delete operation will not work properly unless the entire filename block has been saved and 
restored. 
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Manually Initializing the Filename Block 


In addition to saving and restoring the filename block in anticipation of reopening a file by file 
ID, you can also initialize the filename block manually. You can invoke the .PARSE and .FIND 
routines (see Chapter 4) at appropriate points to build the required fields of the filename block. 
After the .PARSE and .FIND logic is completed, all the information required for opening the file 
exists within the filename block. When any one of the available FCS macro calls that open existin 
files is then issued, FCS unconditionally opens that file by file ID. 


Occasionally, such manual operations are desirable, especially if your program is operating in an 
overlaid environment. In this case, it is highly desirable that the code for opening a file be broker 
into small segments in the interest of conserving memory space. Because the body of code for 
the OPEN$x and .PARSE functions is sizable, two other types of macro calls for opening files are 
provided for use with overlaid programs. The OFID$ and OFNB$ macro calls (see Chapter 3) are 
specifically designed for this purpose. 


The structure recommended for an overlaid environment is to have either the OFID$ or the OFNB 
code on one branch of the overlay and the .PARSE and .FIND code on another branch. Then, if yo 
want your task to open a file by file ID, the PARSE and .FIND routines can be invoked at will to 
insert required information in the filename block before opening the file. 


The OFID$ macro call can be issued only in connection with an existing file. The OFNB$ macro 
call, on the other hand, can be used for opening either an existing file or for creating and opening 
a new file. In addition, the OFNB$ macro call requires only the manual invocation of the .PARSE 
routine to build the filename block before opening the file. 


If conservation of memory is an objective, and if your program will be opening both new and 
existing files, it is recommended that only the OFNB$ routine be included in one branch of the 
overlay; including the OFID$ routine would needlessly consume memory space. 


In all cases, however, it is important to note that all the macro calls for opening existing files are 
sensitive to the presence of any nonzero value in the first word (N.FID) of the filename block. If 
this field contains any value other than 0, the file is unconditionally opened by file ID. This does 
not imply, however, that only the file identification field (N.FID) is required to open the file in 
this manner. The device name field (N.DVNM) and the unit number field (N.UNIT) must also be 
appropriately initialized. The logic of the FCS macro calls for opening existing files assumes that 
these other required fields are present in the filename block if the file identification field contains 
nonzero value. 


Because many programs continually reuse FDBs, the CLOSE$ function (see Chapter 3) puts zeros 
in the file identification field (N.FID) of the filename block. This action prevents the field (which 
pertains to a previous operation) from being used mistakenly to open a file for a current operation 
Thus, if your task later intends to open a file by file ID using information presently in the filenam 
block, the entire filename block (not just N.FID) must be saved before closing the file. Then, at th 
appropriate point in program flow, the filename block can be restored to open the desired file by fil 
ID. 


Initializing the File Storage Region 


The file storage region (FSR) is an area allocated in your program as a buffer pool to accommodats 
the program’s block buffer requirements in performing record I/O (GET$ and PUT$) operations. 
Although the FSR is not applicable to block I/O (READ$ and WRITE$) operations, you must 
issue the FSRSZ$ macro once in every program that uses FCS, regardless of the type of I/O to be 
performed. 


The macro calls associated with the initialization of the FSR are described next. 
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FSRSZ$—-Initialize FSR at Assembly Time 


The MACRO-11 programmer establishes the size of the FSR at assembly time by issuing an 
FSRSZ$ macro call. This macro call does not generate any executable code. It merely allocates 
space for a block-buffer pool in a program section named $$FSR1. The amount of space allocated 
depends on information provided by you, or defaulted, during the macro call. 


NOTE: The FSRSZ$ macro allocates the FCS impure area that is pointed to by a fixed 
location in your task’s virtual memory. This pointer is not altered when overlays are 
loaded; therefore, the FSRSZ$ macro must be invoked in the root segment of a task. 
Unpredictable results might occur if the FSRSZ$ macro is invoked in more than one 
parallel overlay. 


FSRSZ$_fbufs, bufsiz,psect 


Parameters 


fbufs 
Specifies a numeric value that you establish as follows: 


¢ If no record I/O processing is to be done, fbufs equals 0. A value of 0 indicates that an 
unspecified number of files can be open simultaneously for block I/O processing. For example, 
if you intend to access three files for block I/O operations and no files for record I/O operations, 
the FSRSZ$ macro call takes 0 as an argument as follows: 


FSRSZ$ 0 
No other parameters need be specified unless the function of the psect parameter is required. 


e If record I/O, using a single buffer for each file, is to be done, fbufs represents the maximum 
number of files that can be open simultaneously for record I/O processing. For example, you 
might want to access simultaneously three files for block I/O and two files for record I/O. You 
would specify the following FSRSZ$ macro call: 


FSRSZ$ 2 


Additional parameters, bufsiz and psect (described subsequently) could also be specified as 
required. 


¢ If record I/O with multibuffering is to be done, fbufs represents the maximum number of 
buffers ever in use simultaneously among all files open concurrently for record I/O. Assume, for 
example, that your program will simultaneously access four disk files for record I/O operations. 
Assume further that you want double buffering for three of the disk files and have, therefore, 
specified a multibuffer count of 2 in the FDBF$A macro calls (refer to Section 2.3.1.6) for the 
associated files. You would then issue the following FSRSZ$ macro call: 


FSRSZ$ 7 


This macro call indicates that a maximum of seven buffers will be in use simultaneously. This 
total is calculated as follows: one buffer for the single-buffered file and two buffers for each of 
the three double-buffered files. Additional parameters, bufsiz and psect (described next), could 
also be specified as required. 


bufsiz 


Specifies a numeric value defining the total block buffer pool space (in bytes) needed to support the 
maximum number bytes\ master) of files that can be open simultaneously for record I/O. If this 
parameter is omitted, FCS obtains a total block buffer pool requirement by multiplying the value 
specified in the fbufs parameter with a default buffer size of 512 bytes. If, for example, a maximum 
of two single-buffered disk files will be open simultaneously for record I/O, either of the following 
FSRSZ$ macro calls could be issued: 
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FSRSZ$ 2 
FSRSZ$ 2,1024. 


If you want your task to explicitly specify block buffer pool requirements, the following formula 
must be applied: 


bufsiz=(bsizel*mbcl1) (+ (bsize2*mbc2) ... +(bsizen*mbcn) J 


bsize1,osize2, ... ,bsizen 

Indicates the sizes, in bytes, of the buffers to support each file. The size of a buffer for a particula. 
file depends on the device supporting the file if the standard block buffer size is used. Standard 
block sizes for devices are established at system generation time. The override block buffer size 
(ovbs) parameter can be used in the FDBF$x macro call to increase buffer size, as described in 
Section 2.3.1.6; these increases must be considered when you explicitly specify block buffer pool 
requirements. 


mbc1,mbc2, ... ,mbcn 
Indicates the multiple buffer counts (refer to Section 2.3.1.6) specified for the respective files. 


The total value expressed by the bufsiz parameters must always represent the worst case buffer 
pool requirements among all combinations of simultaneously open record I/O files. The number of 
files (or buffers) representing the worst case is expressed as the first parameter of the macro call. 


psect 


Specifies the name of the program section (PSECT) to which control returns after FSRSZ$ 
completes processing. If no name is specified, control returns to the blank PSECT. 


FINIT$—Initialize FSR at Run Time 


In addition to the FSRSZ$ macro call described in the preceding section, the FINIT$ macro call 
must also be issued in a MACRO-11 program to call initialization coding to set up the FSR. 


label: FINIT$ 


Parameter 


label 

Indicates an optional symbol, which you specify, that allows control to be transferred to this 
location during program execution. Other instructions in the program might reference this label, 
as in the case of a program that has been written so that it can be restarted. 


The FINIT$ macro call should be issued in the program’s initialization code. The first FCS call 
issued for opening a file performs the FSR initialization implicitly (if it has not already been 
accomplished through an explicit invocation of the FINIT$ macro call). However, it is necessary, in 
the case of a program that is written so that it can be restarted, to issue the FINIT$ macro call in 
the program’s initialization code, as shown in the next example. This requirement derives from the 
fact that such a program performs all its initialization at run time, rather than at assembly time. 


For example, a program that is not written so that it can be restarted might accomplish the 
initialization of the FSR implicitly through the following macro call: 


START: OPENSR #FDBIN ; IMPLICITLY INITIALIZES THE FSR 
7AND OPENS THE FILE. 


In this case, although transparent to you, the OPEN$R macro call invokes the FINIT$ operation. 
The label START is the transfer address of the program. 
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In contrast, a program that embodies the capability to be restarted must issue the FINIT$ macro 
call explicitly at program initialization as shown here: 


START: FINITS ;EXPLICITLY INITIALIZES THE FSR AND 
OPENSR #FDBIN 7;OPENS THE FILE. 


In this case, the FINIT$ macro call cannot be invoked arbitrarily elsewhere in the program; it 
must be issued at program initialization. Doing so forces the reinitialization of the FSR, whether 
or not it has been done in a previous execution of the program through an OPEN$x macro call. 


It is important to realize that calling any of the file control routines described in Chapter 4, such 
as .PARSE, first requires the initialization of the FSR. However, the FINIT$ operation must be 
performed only once each program execution. Note also that FORTRAN programs issue a FINIT$ 
macro call at the beginning of the program execution; therefore, MACRO-11 routines used with the 
FORTRAN Object Time System (OTS) must not issue a FINIT$ macro call. 


Increasing the Size of the File Storage Region 


Procedures for increasing the size of the FSR for either MACRO-11 or FORTRAN programs are 
presented in Sections 2.8.1 and 2.8.2. 


FSR Extension Procedures for MACRO-11 Programs 


Increase the size of the FSR for a MACRO-11 program by following either of the following 
procedures: 


e Modify the parameters in the FSRSZ$ macro call to redefine the buffer pool requirement of 


files open simultaneously for record I/O processing. Reassemble the program. 


¢ Use the EXTSCT (extend program section) command at task-build time to define the new size 
of the FSR. To invoke this option, specify the command in the following form: 


EXTSCT = S$SFSR1:length 


Parameter 


$$FSR1 


Specifies the symbolic name of the program section within the FSR that is reserved as the 
block buffer pool length. A numeric value defining the total required size of the buffer pool in 
bytes. 


The size of the FSR cannot be reduced at task-build time. 


In calculating the total length of the FSR, you can use either of the following formulas: 
¢ Length = (S.BFHD*fbufs)+bufsiz 
¢ Length = fbufs*(S.BFHD+512;9) 


Length Argument 


S.BFHD 


Specifies a symbol that defines the number of bytes required for each block buffer header. You 
can define this symbol locally in your program by issuing the following macro call: 


BDOFFS DEFSL 
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fbufs 


Specifies a numeric value representing either the maximum number of files open 
simultaneously for record I/O (when single buffering only is used) or the maximum number 
of buffers ever in use simultaneously among all files open concurrently for record I/O (when 
multibuffering is used). Refer also to the description of this parameter in the FSRSZ$ macro 
call in Section 2.7.1. 


bufsiz 

Specifies a numeric value defining the total block buffer pool space (in bytes) needed to support 
the maximum number of files that can be open simultaneously for record I/O. Refer to the 
description of this parameter in the FSRSZ$ macro call in Section 2.7.1. 


51249 
Specifies the standard default buffer size. 


The EXTSCT option is described in detail in the JAS Task Builder Reference Manual. 


FSR Extension Procedures for FORTRAN Programs 


For a FORTRAN program, if an explicit ACTFIL option is not issued to the Task Builder, an 
ACTFIL statement with a default value of 4 is generated during task build. You can extend the 
size of the FSR at task-build time by issuing the following command: 


ACTFIL = files 


Parameter 


files 


Specifies a decimal value defining the maximum number of files that can be open simultaneously 
for record I/O processing. 


This command, like the EXTSCT command described previously, causes program section $$FSR1 
to be extended by an amount sufficient to accommodate the number of active files anticipated for 
simultaneous use by the program. 


The size of the FSR for a FORTRAN program can also be decreased at task-build time. As noted 
previously, the default value for the ACTFIL command is 4. Thus, if 0, 1, 2, or 3 is specified as the 
“files” parameter, the size of $$FSR1 (the FSR block buffer pool) is reduced accordingly. 


The ACTFIL option is described in detail in the JAS Task Builder Reference Manual. 


Coordinating I/O Operations 


Your programs perform all I/O operations by issuing GET$ or PUT$ and READ$ or WRITE$ macro 
calls. (See Chapter 3 for a complete discussion of these file-processing macro calls.) These calls 
do not access the physical devices in the system directly. Rather, when any one of these calls is 
issued, an I/O-related system macro called Queue I/O (QIO$, QIO$C, or QIO$S) is invoked as the 
interface between the File Control Services (FCS) file-processing routines at the user level and 
the system I/O handlers at the device level. Device handlers are included for all the standard I/O 
devices supported by IAS systems. Although transparent to your task, the QUEUE I/O directive is 
used for all FCS file access operations. 


When invoked, the QIO$ macro instructs the system to place an I/O request for the associated 
physical device unit into a queue of priority-ordered requests for that unit. This request is placed 
according to the priority of the issuing task. As required system resources become available, the 
requested I/O transfer takes place. 
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As implied previously, the following two separate and distinct processes are involved in 
accomplishing a specified I/O transfer: 


1 The successful queuing of the GET$ or PUT$ or READ$ or WRITE$ I/O request 


2 The successful completion of the requested data transfer operation 


These processes, both of which yield success/failure indications that can be tested by your program, 
must be performed successfully for the specified I/O operation to be completed. It is important to 
note that FCS totally synchronizes record I/O operations for you, even in the case of multibuffered 
operations. In the case of block I/O operations, the flexibility of FCS allows you to synchronize 

all block I/O activities, thus enabling you. to satisfy logical processing dependencies within the 
program. 


Event Flags 


I/O operations proceed concurrently with other system activity. After an I/O request has been 
queued, the system does not force an implied wait for the issuing task until the requested operation 
is completed. Rather, the operation proceeds in parallel with the execution of the issuing task, and 
it is the task’s responsibility to synchronize the execution of I/O requests. Tasks use event flags in 
synchronizing these activities. The system executes operations that manipulate, test, and wait for 
these indicators of internal task activity. 


The completion of an I/O transfer, for example, is recognized by the system as a significant event. 
If you have specified a particular event flag to be used by the task in coordinating I/O-completion 
processing, that event flag is set, causing the system to evaluate the eligibility of other tasks to 
run. Any event flag from 1 to 329 can be defined for local use by the task. If you have not specified 
an event flag, FCS uses event flag 3219 by default to signal the completion of I/O transfers. 


Specific FDB-initialization and I/O-initiating macro calls in FCS enable you to specify event flags, 
if desired, that are unique to a particular task and that are set and reset only as a result of that 
task’s operation. 


For record I/O operations, such an event flag can be defined through the efn parameter of the 
FDBF$A or the FDBF$R macro call (see Section 2.3.1.6 or 2.3.2, respectively). 


For block I/O operations, an event flag can be declared through the bkef parameter of the FDBK$A 
or the FDBK$R macro call (see Section 2.3.1.4 or 2.3.2, respectively); alternatively, a block event 
flag can be declared through the corresponding parameter of the I/O-initiating READ$ or WRITE$ 
macro call (see Chapter 3). 


In both record and block I/O operations, the event flag is cleared when the I/O request is queued 
and is set when the I/O operation is completed. In the case of record I/O operations, only FCS 
manipulates the event flag. Additionally, the event flag’s state is transparent to your task, which 
must not issue a WAITFOR system directive predicated on the event flag used for coordinating 
record I/O operations. A record I/O operation, for example, might not even involve an I/O transfer; 
rather, it might only involve the blocking or deblocking of a record within the file storage region 
(FSR) block buffer. On the other hand, the event flag defined for synchronizing block I/O operations 
is totally under your control. 


Also, a code indicating the success or failure of the QIO$ macro request resulting from the READ$ 
or WRITE$ macro call is returned to the Directive Status Word (DSW). If desired, you can test the 
symbolic location DSW to determine the status of the I/O request. The success/failure codes for the 
QIO$ macros are listed in the JAS Device Handlers Reference Manual. 
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Event flag directives are described in the IAS Executive Facilities Reference Manual. The 
relationship of event flags to specific devices is described in the JAS Device Handlers Reference 
Manual. 


/O Status Block 


Because of the comparative complexity of block I/O operations, an optional parameter is provided 
in the FDBK$A and the FDBK$R macro calls, as well as in the READ$ and WRITE$ macro calls, 
that enables the system to return status information to your task for block I/O operations. The I/O 
status block (IOSB) is not applicable to record I/O (GET$ or PUT$) operations. 


This optional parameter, called the IOSB address, is made available to FCS through any of the 
macro calls identified previously. When this parameter is supplied, the system returns status 
information to a 2-word block reserved in your program. Although the IOSB is used principally as 
a QIO$ macro housekeeping mechanism for containing certain device-dependent information, this 
area also contains information of particular interest to you. 


Specifically, the second word of the IOSB is filled in with the number of bytes transferred during 
a READ$ or WRITE$ operation. When you are performing READ$ operations, it is good practice 
to use the value returned to the second word of the IOSB as the number of bytes actually read, 
rather than to assume that the requested number of bytes was transferred. Employing this 
technique allows the program to properly read virtual blocks of varying length from a device 
such as a magnetic tape unit, provided that the requested byte count is at least as large as the 
largest virtual block. For WRITE$ operations, the specified number of bytes is always transferred; 
otherwise, an error condition exists. 


Also, the low-order byte of the first word of the IOSB contains a code that reflects the final status 
of the READ$ or WRITE$ operation. The codes returned to this byte can be tested to determine 
the status of any given block I/O transfer. The binary values of these status codes always have the 
following significance: 


Code Value Meaning 

+ (plus sign) I/O transfer completed. 

0 I/O transfer still pending. 
- (minus sign) I/O error condition exists. 


The format of the IOSB and the error codes returned to the low-order byte of its first word are 
described in detail in the JAS Device Handlers Reference Manual. 


If the address of the IOSB is not made available to FCS (and hence to the QIO$ macro) through 
any of the macro calls noted previously, no status information is returned to the IOSB. In this case, 
the fact that an error condition might have occurred during a READ$ or WRITE$ operation is 
simply lost. Thus, supplying the address of the IOSB to the associated File Descriptor Block (FDB) 
is highly desirable and makes normal error reporting easier. 


You can define an IOSB in your task at assembly time through any storage directive logically 
equivalent to the following: 


IOSTAT: .BLKW 2 


IOSTAT is a symbol, which you define, naming the IOSB and defining its address. This symbolic 
value is specified as the bkst parameter in the FDBK$A or the FDBK$R macro call to initialize 
FDB offset location F.BKST; it can also be specified as the corresponding parameter in the READ$ 
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or the WRITE$ macro call. Initializing this cell in the FDB is an integral part of issuing the 
desired I/O request. 


AST Service Routine 


An asynchronous system trap (AST) is a software-generated interrupt that causes the sequence 
of instructions currently being executed to be interrupted and control to be transferred to another 
instruction sequence elsewhere in the program. If desired, you can specify the address of an AST 
service routine that is to be entered upon completion of a block I/O transfer. Because an AST is a 
trap action, it constitutes an indication of block I/O completion. 


You can specify the address of an AST service routine as an optional parameter (bkdn) in the 
FDBK$A or the FDBK$R macro call (see Section 2.3.1.4 or 2.3.2, respectively); this parameter may 
also be specified in the READ$ or the WRITE$ macro call, initializing the FDB at the time the I/O 
request is issued (see Chapter 3). 


Usually, you specify an AST address to enable a running task to be interrupted to execute special 
code upon completion of a block I/O request. If the address of an AST service routine is not 
specified, the transfer of control does not occur, and normal task execution continues. 


The main purpose of an AST service routine is to inform your task that a block I/O operation has 
been completed, thus enabling the program to continue immediately with some other desired (and 
perhaps logically dependent) operation (for example, another I/O transfer). 


If an AST service routine is not provided by you, some other mechanism, such as event flags or 
the IOSB, must be used as a means of determining block I/O completion. In the absence of such a 
routine, for example, you can test the low-order byte of the first word in the IOSB to determine if 
the block I/O transfer has been completed. A WAIT$ macro call (see Chapter 3) can also be issued 
in connection with a READ$ or WRITE$ operation to suspend task execution until a specified event 
flag is set to indicate the completion of block I/O. 


Implementing an AST service routine in your program is application dependent and must be coded 
specifically to meet your task’s particular I/O-processing requirements. A detailed discussion of 
ASTs is beyond the scope of this document. Refer to the IAS Executive Facilities Reference Manual 
for discussions of trap-associated system directives. 


CAUTION: Do not execute any FCS routines while in an AST service routine. FCS 
maintains an impure data area that it uses as a Directive Parameter Block (DPB) and as 
a scratch area for directives. An AST could interrupt an FCS operation that is altering 
this impure area. Executing an FCS routine in AST state could alter the impure area 
and cause unpredictable results when task execution resumes. 


Block Locking 


Block locking selectively controls access to blocks within a file while that file is being read from or 
written to by one or more users. Block locking is a system generation option that can be used from 
FCS or RMS-11 or by issuing QIO$ macros. 


You can enable block locking only when the file is opened. Once block locking is enabled, you can 
establish “locks,” which are structures allocated from system dynamic storage that control access 
to specific blocks in the file. 
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When your task reads or writes a block, the Executive creates a lock that subsequently restricts 
other users from writing to or reading from that block. When your task has a file open on a logica 
unit number (LUN) with block locking enabled and locks are created, your locks do not restrict you 
task from reading or writing blocks if you use the same LUN. Locks can be selectively eliminated 
by issuing a QIO$ macro with the IO.ULK (unlock) function code. You can only eliminate those 
locks that you have created. When your task closes the file, all your locks on that file are released 
to system dynamic storage. 


Block locking operates in the following ways when using FCS: 
1 Opens the file. 


To enable block locking when opening a file from FCS, you must change two fields in the 
FDB. The value FA.SHR in byte F.FACC must be set to allow shared write access to the file. 
Additionally, the values FA.LKL, FA.EXL, and FA.ENB must be set in word F.ACTL. Setting 
FA.SHR causes FCS to clear AC.LCK in the DPB. For example: 


FDOPSR #FDB,,,,#FA.SHR, #FA.LKL!FA.EXL! FA.ENB 
OPENSR RO,,/7++,,ERRSUB ;OPEN SHARED FOR READ WITH LOCKS 


2 Writes or reads blocks. 


A one-block read or write operation locks a block for exclusive access. A write or read operatio1 
of more than one block similarly locks all blocks operated on in this QIO$ macro. A file open 
for block mode might invoke READ$ and WRITE$ macros in the usual manner. 


Note that, in general, FCS operates as follows on sequential read access: 
a. OPEN$R positions the file to record 1. 

b. GET$ returns record 1 and positions the file to record 2. 

c. GET$ returns record 2 and positions the file to record 3. 

d. GET$ returns record 3 and positions the file to record 4. 

Be aware that successive GET$ macros scan across the file sequentially. 


However, if you have files open for record mode operations, the following special consideration: 
might exist: 


¢ A number of tasks are updating records in a single file. 
¢ One of these tasks is reading records sequentially. 


For example, if the GET$ macro for record 2 in the task that reads blocks sequentially fails 
because record 2 is contained in a block previously locked by another task, FCS loses its 
position in the file. The next GET$ macro yields undefined results; it obtains neither record 2 
nor record 3. 


After this kind of error occurs, FCS must re-position its pointer to the records in the file. This 
can happen in one of the following ways: 


¢ Operating in random mode on fixed-length records, FCS re-positions its record pointer to 
the first record for each GET$ or PUT$ operation. 


¢ FCS re-positions the FCS pointer in a file of variable-length records by calling the FCS 
-POINT routine. You can re-position the pointer either to a location noted by a previous 
-MARK call or to the beginning of the file. 


e FCS closes and reopens the file to re-position the pointer to the beginning. 
3 Unlocks blocks. 
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To unlock blocks without closing the file, you must execute a QIO$ macro with the function 
code IO.ULK. You can use IO.ULK to unlock one block, a series of blocks, or all the blocks in 
an open file. 


To unlock one or more blocks in a series, specify the block count in device-dependent parameter 
Word 2, specify the high 8 bits of the starting virtual block number (VBN) in the low byte of 
parameter Word 4, and specify the low 16 bits of the starting VBN in parameter Word 5. For 
example, to unlock previously locked VBNs 5, 6, and 7, use the following code: 


MOV #3,RO0 ; UNLOCK 3 BLOCKS 
MOV #5,R1 ;STARTING AT VBN 5 
QIowss #IO.ULK, #MYILUN, #1, , #IOSB, ,<,RO,,,R1> 


To unlock all blocks you have locked on this LUN, issue the QIO$ macro with no parameters 
beyond the device-independent part of the DPB, as follows: 


QIOWSS #I0.ULK, #MYLUN, #1,,#IOSB ;UNLOCK ALL BLOCKS 
Also, you can use FCS to execute the QIO$ macros for you by calling the .XQIO routine. 


To use the XQIO routine to unlock all blocks that you have locked on this LUN and file, call 
.XQIO with no option parameters, that is, with R2=0 as follows: 


MOV #FDB, RO 7;GET FDB ADDRESS 

MOV #10.ULK, R1 7; UNLOCK BLOCK FUNCTION 

CLR R2 7; UNLOCK ALL BLOCKS 

CALL -XQIO 7; EXECUTE QIO 

BCS ERROUT 7; IF CS ERROR IS IN F.ERR(RO) 


To use .XQIO to unlock one or more blocks in a series, you must set up a 5-word parameter 
block. Specify the count of blocks in Word 2, specify the high 8 bits of the starting VBN in the 
low byte of parameter Word 4, and specify the low 16 bits of the starting VBN in parameter 
Word 5. For example, to unlock the previously locked VBNs 5, 6, and 7, use the following code: 


PRMBK: .WORD 0 7PARAMETER BLOCK FOR UNLOCK QIO 
- WORD 0 COUNT OF BLOCKS TO UNLOCK 
- WORD 0 ; 
-WORD 0 7;HIGH 8 BITS OF START VBN 
- WORD 0 7;LOW 16 BITS OF START VBN 
MOV #FDB, RO 7GET FDB ADDRESS 
MOV #IO.ULK,R1 ;UNLOCK BLOCK FUNCTION 
MOV #5,R2 7FIVE PARAMETERS 
MOV #PRMBK, R3 7ADDRESS OF PARAMETER BLOCK 
MOV #3,2(R3) ; UNLOCK 3 BLOCKS 
MOV #5,8. (RI) 7STARTING AT VBN 5 
CALL -XQIO 7EXECUTE QIO 
BCS ERROUT 7IF CS ERROR IS IN F.ERR(RO) 


4 Closes the file. 


Closing the file in the ordinary manner will release all blocks that have been established on 
that file for the specific task and LUN. 


Error Codes Related to Shared Files and Block Locking 


Error codes relating to file sharing and block locking might be returned in the following 
circumstances. 
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Error Codes 
1 Opening the file 


The following error codes might occur when you attempt to open the file: 


IE.WAC, 


Explanation: Indicates that you have requested that other users be denied write access (no FCS 
FA.SHR or AC.LCK=1), but someone else has already opened the file to write to it. 


User Action: Do not attempt to open the file until all others writing to the file have closed it. 
IE.LCK, 


Explanation: Indicates that one of the following conditions is true: 


¢ You want to write to the file and have allowed shared write access (set FCS FA.SHR or 
AC.LCK=0), but someone else has already opened the file, denying others write access. 


User Action: Do not attempt to open the file until all accessors without shared write access have 
closed the file. 


¢ You want to write to the file and have allowed shared write access (set FCS FA.SHR or 
AC.LCK=0) without enabling block locking but someone else has already opened the file 
with block locking enabled. 


User Action: Open the file with block locking enabled. 


¢ F11ACP cannot perform a directory operation because the directory is locked or being 
written to. 


User Action: The solution depends on what you anticipate as normal activity on your system. If 
it is legitimate for a task to access a directory, then consider attempting the operation again. 


IE.ULK, 


Explanation: Indicates that the Executive does not support block locking. This error can only be 
returned on an IAS system that has been generated without block locking support. 


User Action: Open the file without enabling block locking. 
2 Writing or reading blocks 


The following error codes might occur when you attempt to write or read blocks: 


IE.ULK, 


Explanation: Returned by the Executive when any read or write error occurs that relates to bloc] 
locking. It generally means that another task has locked the block. 


User Action: The solution depends on the application. Wait and retry the operation or report the 
error and stop processing. 


3 Unlocking blocks 
The following error codes might occur when you attempt to unlock blocks: 
IE.IFC, . 
Explanation: Returned when the Executive does not support block locking. 
User Action: Do not attempt to unlock blocks on a system that does not support block locking. 
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IE.LCK, 


Explanation: Returned upon the occurrence of any other error. For example, IE.LCK is returned 
if another task has locked the blocks. 


User Action: Unlock only those blocks that you have previously locked for that file. 
4 Closing the file. 


No block locking error can occur when closing a file. 
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You can manipulate files through a set of file-processing macro calls. The assembler invokes and 
expands these macros at assembly time and the operating system executes the resulting code at 
run time. This chapter describes these run-time macro calls, which allow you to manipulate files 
and to perform the following I/O operations. Table 3—1 provides a brief description of each macro. 


Table 3-1 File-Processing Macro Calls 


Macro 

Call Function 

OPENS Opens and prepares a file for processing. 

OPNS$ Opens and prepares a file for processing and allows shared access to that file (depending on the 
mode of access.) 

OPNT$ Creates and opens a temporary file for processing. 

OFID$ Opens an existing file by using file identification information in the filename block. 

OFNB$ Opens a file by using file name information in the filename block. 

CLOSE$ Terminates file processing in an orderly manner. 

GET$ Reads logical data records from a file. 

GET$R Reads fixed-length records from a file in random mode. 

GET$S Reads records from a file in sequential mode. 

PUT$ Writes logical data records to a file. 

PUT$R Writes fixed-length records to a file in random mode. 

PUT$S Writes records to a file in sequential mode. 

READ$ Reads virtual data blocks from a file. 

WRITES Writes virtual data blocks to a file. 

WAIT$ Suspends program execution until a requested block I/O operation is completed. 

DELET$ Removes a named file from the associated volume directory and deallocates the space occupied by 


the file. 


Most of the parameters associated with the file-processing macro calls supply information to the 
File Descriptor Block (FDB). Such parameters cause MOV or MOVB instructions to be generated 
in the object code, which results in the initialization of specific locations within the FDB. 


The final parameter in all file-processing macros is the symbolic address of an optional, 
user-defined error-handling routine. This routine is entered upon detection of an error condition 
during the file-processing operation. When this optional parameter is specified, the following code 
is generated: 


Code for macro 


Bcc -+6 7;TESTS CARRY BIT IN PROCESSOR STATUS WORD. 
CALL ERRLOC 7; INITIATES ERROR-HANDLING ROUTINE 
;AT "“ERRLOC" ADDRESS. 
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If the operation is completed successfully, the Carry bit in the Processor Status Word (PSW) is not 
set, and FDB offset location F ERR contains a positive value. The BCC instruction then results in 
a branch around the CALL instruction and normal program execution continues. 


However, if an error condition is detected during the execution of the file-processing routine, the 
Carry bit in the PSW is set, FDB offset location F ERR contains a negative value (indicating an 
error condition), and the branch around the CALL instruction does not occur. Instead, the CALL 
instruction is executed, loading the program counter (PC) with the symbolic address (ERRLOC) of 
the error-handling routine and initiating its execution. 


If this optional parameter is not specified, the error-processing routine is not called, and you must 
explicitly test the Carry bit in the PSW to ascertain the status of the requested operation. 


Note that executing the File Control Services (FCS) file-processing routines causes all your task’s 
general registers, except RO, to be saved. FCS uses RO by convention to contain the address of the 
FDB associated with the file being processed. 


OPEN$x—Generalized Open Macro 


Before any file can be processed by your task or system program, it must first be opened. An 
alphabetic suffix accompanying the macro name indicates to FCS the action you intend to perform 
on a file. For example, you might issue a generalized macro. 


OPENS$x 


Parameter 


x 


Represents any one of the following alphabetic suffixes, each of which denotes a specific type of file 
processing: 


Read an existing file. 


R 

W Write (create) a new file. 

M Modify an existing file without changing its length. 
U 


Update an existing file and extend its length, if necessary. 


> 


Append (add) data to the end of an existing file. 


NOTE: You can issue the generalized OPEN$x macro without an alphabetic suffix. 

In this case, the action to be performed on the file is indicated to FCS through an 
additional parameter in the macro. This value, called the file access (facc) parameter, 
causes offset location F.FACC in the associated FDB to be initialized. Section 3.7 
describes this macro in detail. 


Depending on the alphabetic suffix supplied in the OPEN$x macro call, certain other types of 
operations might or might not be allowed, as follows: 


¢ If Ris specified (for reading an existing file), that file cannot also be written; that is, a PUT$ or 
WRITES operation cannot be performed on that file. 


¢ If M or U is specified (for modifying or updating an existing file), that file can be both read 
and written; that is, concurrent GET$ and PUT$ or READ$ and WRITE$ operations can be 
performed on that file. 


¢ IfM is specified (for modifying an existing file), that file cannot be extended. 


¢ If W or A is specified (for creating a new file or for appending data to an existing file), that file 
can be read, written, or extended. 
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The program that issues the OPEN$x macro must have appropriate access privileges for the 
specified action. Table 3-2 summarizes the access privileges for the various forms of the OPEN$x 
macro. This table also shows where the next record or block will be read or written in the file after 
it is opened. 


Table 3-2 File Access Privileges Resulting from OPEN$x Macro 


Macro Access Privileges Position of File After OPEN$x 
OPEN$R Flead First record of existing file 
OPENSW Read, write, extend First record of new file 
OPENS$M Ftead, write First record of existing file 
OPEN$U Read, write, extend First record of existing file 


OPENS$A Read, write, extend End of existing file (For special PUT$R considerations, see 
Section 3.13.) 


When your task issues any form of the OPEN$x macro, FCS first fills in the filename block with 
file name information retrieved from the data-set descriptor (see Chapter 2). FCS gains access to 
this data structure through the address value stored in FDB offset location F.DSPT. 


If any required data has been omitted from the data-set descriptor, FCS attempts to obtain the 
missing information from the default filename block. This data structure, which can also contain 
file name information specified in your task, is created in the program by issuing the NMBLK$ 
macro (see Chapter 2). FCS gains access to this structure through the address value stored in FDB 
offset location F.DFNB. 


The address values in offset locations F DSPT and F.DFNB can be supplied to FCS through 
the FDOP$A macro, the FDOP$R macro call, or the OPEN$x macro. FCS requires access to 
the data-set descriptor or the default filename block in retrieving file name information used in 
opening files. 


If a new file is to be created, the OPEN$W macro is issued. FCS then performs the following 
operations: 


1 Creates a new file and obtains file identification information for the file. FCS maintains the 
file identification information in offset location N.FID of the filename block. The filename block 
in the FDB begins at the FDB offset location F.FNB. 


2 Initializes the file attribute section of the file header block. The file header block is a file 
system structure maintained on the volume containing the file. Each file on a volume has an 
associated file header block that describes the attributes of that file. FCS obtains attribute 
information for a new file from the FDB associated with the file. The format and content of a 
file header block are presented in detail in Appendix C. 


3 Places an entry for the file in the User File Directory (UFD). If, however, an entry for a file 
having the same name, type, and version number already exists in the UFD, the old file is 
deleted. If your task explicitly issues a particular type of macro that specifies that the file not 
be superseded, the old file is not deleted and an error code-is returned. This type of OPEN$ 
operation is described in Section 3.7. 


Associates the assigned logical unit number (LUN) with the file to be created. 


Allocates a buffer for the file from the file storage region (FSR) block buffer pool if record I/O 
(GET$ or PUT$) operations are processing the file. 
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If an existing file is to be opened, any one of the following macros can be issued: OPEN$R, 
OPEN$M, OPEN$U, or OPEN$A. FCS then performs the following operations: 


1 If file identification information is not present in the filename block, FCS constructs 
the filename block from information taken from the data-set descriptor and the default 
filename block, or both. FCS then searches the UFD by file name to obtain the required 
file identification information. When found, this information is stored in the filename block, 
beginning at offset location N.FID. 


2 Associates the assigned LUN with the file. 


Reads the file header block and initializes the file attribute section of the FDB associated with 
the file being opened. 


4 Allocates a buffer for the file from the FSR block buffer pool if record I/O (GET$ or PUT$) 
operations are processing the file. 


NOTE: As described in Chapter 2, you allocate buffers through the FSRSZ$ macro. The 
number of buffers allocated is dependent upon the number of files that you intend to 
open simultaneously for record I/O operations. 


If your task uses block I/O operations, FDB offset location F.RACC must be initialized with the 
FD.RWM parameter by the FDRC$A, the FDRC$R, or the generalized OPEN$x macro. This 
parameter inhibits the allocation of a buffer when the file is opened. 


Format of Generalized OPEN$x Macro 
The OPEN$x macro takes the general form shown next. 


OPEN$x § fdb,lun,dspt,racc,urba,urbs,err 


Parameters 


x 


Represents the alphabetic suffix specified as part of the macro name, which indicates the desired 
type of operation to be performed on the file. The possible values for this parameter are: R, W, M, 
U, A, or no value at all (see Section 3.1). 


fdb 
Specifies a symbolic value of the address of the associated FDB. 


lun 


Specifies the LUN associated with the desired file. This parameter identifies the device on which 
the volume containing the desired file is mounted. Normally, the LUN associated with the file 
is specified through the corresponding parameter of the FDOP$A or the FDOP$R macro. If so 
specified, the lun parameter need not be present in the OPEN$x macro. Each FDB must have a 
unique LUN. 


dspt 

Specifies the symbolic address of the data-set descriptor. Normally, this address value is specified 
through the corresponding parameter of the FDOP$A or the FDOP$R macro. If so specified, this 
parameter need not be present in the OPEN$x macro. 


This parameter specifies the address of the manually created data-set descriptor (see Chapter 2). 
If the Command String Interpreter (CSI) interprets command lines dynamically, this parameter 
specifies the address of the data-set descriptor within the CSI control block (see offset location 
C.DSDS in Chapter 6). 
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racc 

Specifies the record access byte. One or rnore symbolic values can be specified in this field to 
initialize the record access byte (F.RACC) in the associated FDB. You can specify any combination 
of the following parameters by separating them with exclamation points: 


FD.RWM Requests that block I/O (READ$ or WRITE$) operations are to process the file. If you do not specify 
this parameter, FCS assumes by default that record I/O (GET$ or PUT$) operations are to process 
the file. 


FD.RAN Requests random access to the file for record VO (GET$ or PUT$) operations. The file is opened 
and the first record is pointed to. With this parameter, a PUT$ operation in the file, without exception, 
does not truncate the file. If this parameter is not specified, FCS uses sequential access by default. 
Refer to Chapter 1 for a description of random access mode. 


FD.PLC Requests locate mode (see Chapter 1) for record I/O (GET$ or PUT$) operations. If this parameter is 
not specified, FCS uses move mode (see Chapter 1) by default. 


FD.INS Requests that a PUT$ operation in sequential mode in the body of a file does not truncate the file. 
This parameter prevents the logical end of the file from being reset to a point just beyond the inserted 
record. If this parameter is not specified, a PUT$ operation in sequential mode truncates the file to a 
point just beyond the inserted record, but no deallocation of file blocks occurs. 


Specifying this parameter allows a data record in the body of the file to be overwritten. Care must 
be exercised, however, to ensure that the record being written is the same length as that of the 
record being replaced. 


If the record access byte in the FDB has aneaay been initialized through the corresponding 
parameters of the FDRC$A or the FDRC$R macro, the racc parameters need not be present in the 
OPENS$x macro. 


urba 
Specifies the symbolic address of your task’s record buffer. This parameter initializes FDB offset 
location FURBD+2. 


If your task’s record buffer address has already been supplied to the FDB through the 
corresponding parameter of the FDRC$A or the FDRC$R macro, this parameter need not be 
present in the OPEN$x macro. 


urbs 


Specifies a numeric value that defines the size of your task’s record buffer (in bytes). This 
parameter initializes FDB offset location F.URBD. 


If the size of your task’s record buffer has already been supplied to the FDB through the 
corresponding parameter of the FDRC$A or the FDRC$R macro, this parameter need not be 
present in the OPEN$x macro. 


err 
Specifies the symbolic address of an optional, user-coded error-handling routine. 


Specific FDB requirements for record I/O Operanon: (GET$ and PUT$ macros) are detailed in 
Sections 3.9.2 and 3.12.2. 


The examples listed at the end of this section show sample uses of the OPEN$x macro. 


Note 


You can use RO only to pass the FDB address parameter. Any other use of RO when you issue the 
OPEN$A macro will fail. 
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Examples 
OPENSM RO, #INLUN,, #FD.RAN!FD.PLC 
Opens and modifies an existing file. 


Note in this macro that the FDB address is assumed to be present in RO. The third parameter, 
that is, the data-set descriptor pointer, is not specified; this null specification (indicated by the 
extra comma) assumes that FDB offset location F.DSPT (if required) has already been initialized. 
The last parameter, consisting of two values separated by an exclamation point, establishes random 
access and locate modes for GET$ or PUT$ operations. 


OPENSU RO, #INLUN,,, #RECBUF, #80. 
Updates an existing file. 


This macro also assumes that the FDB address is in RO. Note also that the dspt and racc 
parameter fields are null, based on the premise that the data-set descriptor pointer (F.DSPT) 
has been provided previously to the FDB and that the record access byte (F.RACC) has also 
been previously initialized. Finally, the last two parameters establish the address and the size, 
respectively, of your task’s record buffer. 


OPENSA #OUTFDB 
Shows a macro that might be issued to allow data to be appended to the end of a file. 


This macro specifies the address of an FDB as the only parameter. In this case, it is assumed that 
all other parameters required by FCS in opening and operating on the file have been previously 
supplied to the FDB through the appropriate assembly-time or run-time macro. 


Note in all three preceding examples that the error parameter is not specified, requiring that you 
explicitly test the Carry bit in the PSW to ascertain the success of the specified operation. 


FDB Requirements for Generalized OPEN$x Macro 


The information required for opening a file can be supplied to the File Descriptor Block (FDB) 
through the following macros: 


¢ The assembly-time macros described in Chapter 2 
¢ The NMBLK$ macro described in Chapter 2 
¢ The run-time macros described in Chapter 2 


¢ The various macros described in this chapter for opening files 


The use of any particular combination of macros to define and initialize the FDB is a matter of 
choice, as indicated previously. Of far greater significance is the fact that certain information must 
be present in the FDB before you can open the associated file. In this regard, the following rules 
apply for creating and opening new files, for opening existing files, and for specifying desired file 
options: 


1 Tocreate a new file 


If a new file is to be created through the OPEN$W macro, the following information must first 
be supplied to the FDB. You can specify this information through the FDAT$A macro or the 
FDAT$R macro (see Chapter 2): 


a. The record type must be established for record I/O operations. 
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The record type cannot be supplied to the FDB through any of the various macros used 
to create or open files (for example, OPEN$W, OPEN$R, and so forth). Furthermore, 
this information is not required when opening an existing file because FCS obtains such 
information from the first 14 bytes of your task’s file attribute section of the file header 
block (see Appendix C). 


To establish the record type, you must initialize byte offset location F.RTYP with the 
following symbolic values: 


R.FIX Requests that fixed-length records are to be written into the file. 
R.VAR Requests that variable-length records are to be written into the file. 
R.SEQ Requests that sequenced records are to be written into the file. 


The desired record attributes must be specified for record I/O operations. 


The record attributes cannot be supplied to the FDB through any of the various macros 
used to create or open files (for example, OPEN$W, OPEN$R, and so forth). Furthermore, 
the record attributes are not required when opening an existing file because FCS obtains 
such information from the first 14 bytes of your task’s file-attribute section of the file 
header block (see Appendix C). 


The record attributes are defined by initializing byte offset location F.RATT with the 
appropriate value or values, as follows: 


FD.FTN Requests that the first byte of each record contain a FORTRAN carriage-control character. 
FD.CR Requests that a line-feed (<LF>) character precede each record and that a carriage-return 
(<CR>) character follow the record when that record is output to a device requiring carriage 
control information (for example, to a terminal). The <LF> and <CR> characters are not actually 
embedded within the record. Their presence is merely implied through the file attribute FD.CR. 
FD.BLK Requests that records be prevented from crossing block boundaries. 


FD.PRN Requests that the record be preceded by a word containing carriage-control information. Files 
with this attribute must also be sequenced files; that is, files with the bit R.SEQ set in the byte 
F.RTYP in the FDB. For more information about FD.PRN as a record attribute, see Chapter 2. 


If fixed-length records are to be written to the file, you must specify the record size (in 
bytes) for record I/O operations to appropriately initialize FDB offset location F.RSIZ. 


The record size cannot be supplied to the FDB through any of the various macros used 
to create and open files, (for example, OPEN$W, OPEN$R, and so forth). Furthermore, 
the record size is not required when opening an existing file, because FCS obtains such 
information from the first 14 bytes of your task’s file-attribute section of the file header 
block (see Appendix C). 


To open either a new file or an existing file 


Regardless of whether the file being opened is yet to be created or already exists, the following 
information must be present in the FDB before that file can be opened: 


a. 


The record access byte must be initialized for record or block I/O operations. The symbolic 
values following can be specified in the FDRC$A macro (see Chapter 2), the FDRC$R 
macro call (see Chapter 2), or the generalized OPEN$x macro to initialize FDB offset 
location F.RACC: 


FD.RWM Requests that READ$ or WRITE$ (block I/O) operations process the file. If this parameter is 
not specified, GET$ or PUT$ (record I/O) operations result by default. 
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FD.RAN Requests that random access mode (GET$ or PUT$ record I/O) process the file. The file is 
opened and the first record pointed to. If this parameter is not specified, sequential access 
mode results by default. Refer to Chapter 1 for a description of random access mode. 


FD.PLC Requests that locate mode (GET$ or PUT$ record I/O) process the file. If this parameter is 
not specified, move mode results by default. 

FD.INS Requests that a PUT$ operation in sequential mode in the body of a file shall not truncate the 
file. If this parameter is not specified, a PUT$ operation truncates the file. In this case, the 
logical end of the file is reset to a point just beyond the inserted record, but no deallocation 
of file blocks occurs. 


Your task’s record buffer descriptors (that is, the urba and urbs parameters) and urbs 
parameters \ master) must be specified for record I/O operations. To accomplish this, the 
FDRC$A, the FDRC$R, or the generalized OPEN$x macro can be used. The selected macro 
call defines the address and the size of the area reserved in the program for use as a buffer 
during record I/O operations. The urba and urbs parameters initialize FDB offset locations 
F.URBD+2 and F.URBD, respectively. 


FDB requirements specific to GET$ and PUT$ operations in move and locate mode are 
presented in detail in Sections 3.9.2 and 3.12.2, respectively. 


You must specify the logical unit number (LUN) to initialize FDB offset location F.LUN. 
Initialization of this cell can be accomplished with the lun parameter of the FDOP$A, the 
FDOP$R, or the generalized OPEN$x macro. Each FDB must have a unique LUN. 


If file identification information is not already present in the FDB, either the data-set 
descriptor pointer (F.DSPT) or the default filename block address (F.DFNB) must be 
specified to enable File Control Services (FCS) to obtain required file name information for 
use in opening the file. These address values can be specified in either the FDOP$A macro 
(see Chapter 2) or the FDOP$R macro (see Chapter 2). The generalized OPEN$x macro 
(see Section 3.1) can also be used to specify the data-set descriptor pointer. 


If desired, an event flag number for synchronizing record I/O operations must be specified 

to initialize FDB offset location F.EFN. This optional parameter may be specified in either 
the FDBF$A macro (see Chapter 2) or the FDBF$R macro (see Chapter 2). If not specified, 
FCS uses event flag number 329 by default to synchronize all record I/O activity. 


To specify desired file options 


If certain options are desired for a given file, they must be specified before that file is opened. 

Because this information is needed only in opening the file, it is zeroed when the file is closed, 
thus ensuring that the FDB is properly reinitialized for subsequent use. The options that may 
be specified for a given file are as follows: 


The override block size (ovbs parameter) must be specified in either the FDBF$A or the 
FDBF$R macro to initialize FDB offset location FOVBS. This parameter need be specified 
only if the standard default block size in effect for the associated device is to be overridden 
or if the big-buffering or multibuffering versions of FCS are in use. The override block size 
is specified to improve I/O system performance with record I/O and with record-oriented 
devices (such as line printers) and sequential devices (such as magnetic tape units). (See 
Chapter 2.) 


The multiple buffer count (mbct parameter) must be specified in either the FDBF$A or 
the FDBF$R macro to initialize FDB offset location F.MBCT. If multibuffered record I/O 
operations are to be used, this parameter must be greater than 1, and it must agree with 
the desired number of buffers to be used. This parameter is neither overlaid nor zeroed 
when the file is closed. 
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If the multiple buffer count is not established as described previously, multibuffered 
operations can still be invoked by changing the default buffer count in the file storage 
region (FSR). A default buffer count of 1 is stored in symbolic location MBFCT of $$FSR2. 
This default value can be altered to reflect the number of buffers intended for use during 
record I/O operations. The procedure for modifying this cell in $$FSR2 is described in 
Chapter 2. 


In addition, if your task uses multibuffering, you must specify the appropriate control 
flag as the mbfg parameter in either the FDBF$A or the FDBF$R macro to appropriately 
initialize FDB offset location F MBFG. Either of two symbolic values can be specified for 
this purpose, as follows: 


FD.RAH Requests that read-ahead operations are to process the file. 
FD.WBH Requests that write-behind operations are to process the file. 


Offset location F.MBFG need be initialized only if the standard default buffering 
assumptions are inappropriate. When a file is opened for reading (OPEN$R), read-ahead 
operations are assumed by default; for all other forms of OPEN$x, write-behind operations 
are assumed. It may be useful, for example, to override the write-behind default 
assumption for a file opened through the OPEN$M or the OPEN$U macro when that 

file is being used basically for sequential read operations, but scattered updating is also 
being performed. 


To allocate required file space at the time a file is created, the cntg parameter must be 
specified in either the FDAT$A or the FDAT$R macro. This parameter initializes FDB 
offset location F.CNTG. A positive value specifies results in the allocation of a contiguous 
file having the specified number of blocks; a negative value, on the other hand, results in 
the allocation of a noncontiguous file having the specified number of blocks. 


The address of the 5-word statistics block in your program must be moved manually into 
FDB offset location F.STBK. This address value specifies an area in your task to which FCS 
returns certain statistical information about a file when it is opened. If this parameter is 
not specified, no return of such information occurs. 


The format and content of the statistics block are presented in Appendix D. You can define 
such an area in a program with coding logically equivalent to the following: 


STBLK: .BLKW 5 
Offset location F.STBK may then be initialized manually, as follows: 
MOV #STBLK, FDBADR+F .STBK 


STBLK is the symbolic address of the statistics block, which you define. The destination 
operand of this instruction defines the appropriate offset location within the desired FDB. 


OPNS$x—Open File for Shared Access 


The OPNS$x macro opens a file for shared access. This macro has the same format; that is, it 
takes the same alphabetic suffixes and run-time parameters as the generalized OPEN$x macro. 
The shared access conditions that result from the use of this macro are summarized in Chapter 1. 
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OPNT$W—Create and Open Temporary File 


The OPNT$W macro creates and opens a temporary file for some special purpose of limited 
duration. If a temporary file is to be used only once, it is best created through the OPNT$D macro 
described in Section 3.4. 


The OPNT$W macro creates a file but does not enter a file name for that file into any associated 
User File Directory (UFD). 


In using the OPNT$W macro, you bear the responsibility for marking the temporary file for 
deletion, as described in the procedure in the following text. Then, after all operations associated 
with that file are completed, closing the file results in its deallocation. All space formerly occupied 
by the file is then returned for reallocation to the pool of available storage on the volume. 


Although the OPNT$W macro takes the same format and parameters as those of the generalized 
OPEN$x macro, the former executes faster because no directory entries are made for a temporary 
file. 


Creating a temporary file is usually done when a program requires a file only for the duration 
of its execution (for example, for use as a work file). The general sequence of operations in such 
instances proceeds as follows: 


1 Open a temporary file by issuing the OPNT$W macro. Perform any desired operations on 
that file. If the file is to be used only for a single OPNT$W/CLOSE$ sequence, go to step 6; 
otherwise, continue with step 2. 


2 Before closing the file for processing, save the filename block in the associated FDB. The 
general procedure for saving (and restoring) the filename block is discussed in Chapter 2. 


3 Close the file by issuing the CLOSE$ macro (see Section 3.8). Continue other processing in the 
program, as desired. 


4 In anticipation of reopening the temporary file, restore the filename block to the FDB by 
reversing step 2. 


5 Reopen the file by issuing any of the FCS macros that open existing files. Resume operations 
on the file; repeat the save, CLOSE$, restore, open sequence any desired number of times. 


6 Before closing the file for the last time, call the MRKDL routine, to mark the file for deletion 
as follows: 


CALL .MRKDL 
The .MRKDL routine is described in Chapter 4. 
7 Close the file by issuing the CLOSE$ macro. 


If the filename block is not saved, the file identification field therein is destroyed because this field 
is reset to 0 when the file is closed. 


Thus, if you do not save the filename block before closing a temporary file, a “lost” file results 
because no directory entry is made for a temporary file. Therefore, the usual procedure of listing 
the volume’s directory is inapplicable. The only way such a file can be recovered is to use the File 
Structure Verification Utility program (VFY) to search the volume’s index file. The VFY program 
has the capability to compare the files listed in all the directories on the volume with those listed 
in the index file. If a file appears in the index file, but not in a directory, VFY identifies that file 
for you. This program is described in detail in the RSX-11M/M-PLUS Utilities Manual. 
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OPNT$D-—Create and Open Temporary File and Mark for Deletion 


The OPNT$D macro creates and opens a temporary file. This macro is a convenient way to perform 
steps 1 and 6 shown in Section 3.3. A file marked for deletion cannot be opened by another 
program. Furthermore, when the file is closed, it is deleted from the volume, which returns its 
space to the pool of available storage on the volume for reallocation. 


The presumption in issuing the OPNT$D macro is that the created file is to be used only once. 
This is a desirable way to open a temporary file because the file will be deleted even if the program 
terminates abnormally without closing the file. 


The following OPNT$D macro takes the same format and parameters as those of the generalized 
OPEN$x macro (as described in Section 3.1.1): 


OPNTSD fdb,lun,dspt, racc, urba, urbs,err 
Note 


If the OPNT$D macro is used for a temporary file containing sensitive information, it is 
recommended that you zero the file before closing it, or reformat the disk to destroy the sensitive 
information. (Although a temporary file is deleted after use, the information physically remains on 


' the volume until written over with another file, and it could be analyzed by unauthorized users.) 


OFID$x—Open File by File ID 


You issue the OFID$x macro to open an existing file that uses information stored in the file 
identification field (offset location N.FID) of the filename block in the FDB (not in your default 
filename block). Thus, when you issue this macro, it invokes an FCS routine that opens a file only 
by file ID (see Chapter 2). The following OFID$x macro, which has the same format and takes 
the same parameters as those of the generalized OPEN$x macro (see Section 3.1), is for use with 
overlaid programs: 


OFIDSx fdb,lun,dspt, racc,urba, urbs,err 


In describing the functions of the OFID$x macro, either one of the following two assumptions may 
apply: 


¢ The necessary context for opening the file has been saved from a previous OPEN$x operation 
and has been restored to the filename block in anticipation of opening that file by file ID. 
Saving and restoring the filename block are discussed in detail in Chapter 2. 


¢ The desired file is to be opened for the first time. In that case, the necessary context for 
opening the file must first be stored in the filename block before the OFID$ macro can be 
issued. 


In most cases, the latter assumption apples, requiring that the following procedures be performed: 


1 Call the .PARSE routine (see Chapter 4). This routine takes information from a specified 
data-set descriptor or default filename block, or both, and initializes and fills in the specified 
filename block. 


2 Call the .FIND routine (see Chapter 4). This routine locates an appropriate directory entry for 
the file (by file name) and stores the file identification information found there in the 6-byte file 
identification field of the filename block, starting at offset location N.FID. (As a result of steps 
1 and 2, the necessary context then exists in the associated filename block for opening the file 
by file ID.) 
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3 Issue the OFID$x macro. 


The advantage of using the PARSE and .FIND routines with the OFID$x macro is that you can 
overlay the program, placing .PARSE and .FIND on one branch, and the code for OFID$x on 
another branch. This overlay structure reduces the program’s overall memory requirements. 


Unlike the other FCS macros for opening files, the OFID$x macro requires a nonzero value in 
the first word of the file identification field (N.FID) to work properly. When this field contains a 
nonzero value, FCS assumes that the remaining context necessary for opening that file is present 
and, accordingly, opens the file by file ID. 


Opening an existing file by file ID for write access is a special case. Because you are intending to 
rewrite the existing file, the following occur: 


¢ Any initial allocation (F.CNTG) is ignored. 
e File access byte (F. FACC) value NA.NSP (do not supersede file) is ignored. 


e 6File access byte (F.FACC) value FA.CRE (create new file) is set even though the file is being 
rewritten rather than created. 


° This operation may not be performed on American National Standards Institute (ANSI) 
magnetic tape. The data in the file header labels is not changed when the file is written. See 
Chapter 5 for information on positioning file on tape to rewrite a file in a particular position. 


The OFID$W macro is equivalent to the OFID$U macro. Invoking either OFID$W or OFID$U 
opens an existing file by file ID number for update and extension. 


OFNB$x—Open File by Filename Block 


The OFNB$x macro either opens an existing file or creates and opens a new file by using file name 
information in the filename block. Like the OFID$x macro previously described, the OFNB$x call 
is for use with overlaid programs. However, the OFNB$x macro differs in two important respects: 
it can be issued to create a new file, and it can be issued to open a file by filename block. 


The following OFNB$x call has the same format and takes the same parameters as those of the 
generalized OPEN$x macro (as described in Section 3.1.1): 


OFNBSx fdb,lun,dspt, racc,urba, urbs,err 


The OFNB$x macro also uses the same suffixes that are available to the OPEN$x macro: OFNB$R 
OFNB$W, OFNB$M, OFNB$U, OFNB$A. The suffixes have the same meaning as they do for 
OPEN$x (see Table 3—2). 


The same assumptions outlined for OFID$x apply to the functions of the OFNB$x macro; namely, 
that the filename block has been saved and restored in anticipation of issuing the OFNB$x macro, 
or that the file is being opened for the first time. Because the procedures for saving and restoring 
the filename block are detailed in Chapter 2, the following discussion assumes that the desired file 
is being opened for the first time. In this case, the filename block in the FDB must be initialized. 


To open a file by filename block, the following information must be present in the filename block of 
the associated FDB: 


°¢ The file name (offset location N.FNAM) 

¢ The file type or extension (offset location N.FTYP) 
¢ The file version number (offset location N.FVER) 
°¢ The directory ID (offset location N.DID) 
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¢ The device name (offset location N.DVNM) 
e¢ The unit number (offset location N.UNIT) 


In providing the information to the filename block, you can use either of two general procedures, 
which are described in Sections 3.6.1 and 3.6.2. 


Data-Set Descriptor or Default Filename Block 


If the data-set descriptor contains all the required information listed previously, perform the 
following procedure: 


1 Call the PARSE routine (see Chapter 4). This routine takes information from a specified 
data-set descriptor and default filename block, and the routine fills in the appropriate offsets of 
a specified filename block. 


2 Issue the OFNB$x macro. 


Default Filename Block Only 


If a default filename block is to be used in providing the required information to FCS, perform the 
following procedure: 


1 Issue the NMBLK$ macro (see Chapter 2) to create and initialize a default filename block. 
With the exception of the directory ID, this structure provides all the requisite information to 
FCS. 


2 Call either of the following routines to provide the directory ID: 


— Call the .GTDIR routine (see Chapter 4) to retrieve the directory ID from the specified 
data-set descriptor and to store the directory ID in the default filename block. 


— Call the .GTDID routine (see Chapter 4) to retrieve the default User Identification Code 
(UIC) from $$FSR2 and to store the directory ID in the default filename block. 


3 Move the entire default filename block manually into the filename block associated with the 
file being opened. 


4 Issue the OFNB$x macro. 


Note that the coding for OFNB$x operations normally resides in an overlay apart from that 
containing the other File Control Services (FCS) routines identified previously. 


Issuing the OFNB$x macro is usually done under the premise that the filename block contains 
the requisite information, as described previously. However, if the file identification field (offset 
location N.FID) in the filename block contains a nonzero value when the call to OFNB$x is issued, 
the file is unconditionally opened by file ID. 


If you expect to open both new and existing files, and memory conservation is an objective, 
the OFNB$x macro is most suitable for opening such files. The OFID$x coding should not be 
included in the same overlay with OFNB$x, because OFID$x overlaps the function of OFNB$x 
and, therefore, needlessly consumes memory space. 
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OPEN$—Generalized Open for Specifying File Access 


Usually, when you want to create a file, the file name and the file type are specified, and FCS is 
allowed to assign the next higher file version number. However, if the OPEN$W macro is issued for 
a file having an explicit file name, file type, and file version number, and a file of that description 
already exists in the specified User File Directory (UFD), the old file is superseded. 


By issuing the OPEN$ macro without an alphabetic suffix, and by specifying two additional 
parameters, you can inhibit the superseding of a file when a duplicate file specification is 
encountered in the UFD. Rather than deleting the old version of the file, an error indication 
(IE.DUP) is returned to offset location F.ERR of the applicable File Descriptor Block (FDB). 


All parameters of this macro are identical to those specified for the generalized OPEN$x macro (see 
Section 3.1), with the exception of the facc parameter and the dfnb parameter. These additional 
parameters are described in this section. 


OPEN$  fdb,facc,lun,dspt,dfnb,racc,urba,urbs,err 


Parameters 


facc 


Specifies any one or an appropriate combination of the following symbolic values, which indicate 
how the specified file is to be accessed: 


FO.RD Requests that an existing file is to be opened for reading only. 

FO.WRT Requests that a new file is to be created and opened for writing. 

FO.APD Requests that an existing file is to be opened and appended. 

FO.MFY Requests that an existing file is to be opened and modified. 

FO.UPD Requests that an existing file is to be opened, updated, and, if necessary, extended. 


FA.NSP Requests, in combination with FO.WRT, that the old file having the same file specification is not to be 
superseded by the new file. 


FA.TMP Requests, in combination with FO.WRT, that the file is to be a temporary file. 
FA.SHR Requests that the file is to be opened for shared access. 


dfnb 


Specifies the symbolic address of the default filename block. This parameter is the same as that 
described in connection with the FDOP$A/FDOP$R macro. 


The previously described parameters initialize FDB offset locations F.FACC and F.DFNB with the 
appropriate value. 


Any logically consistent combination of the previously described file access symbols is permissible. 
The particular combination required to create and write a new file without superseding an existing 
file follows: 


OPENS #OUTFDB, #FO.WRT!FA.NSP 
The following macro creates a temporary file for shared access: 


OPENS #OUTFDB, #FO.WRT!FA.TMP!FA.SHR 


Note 


You can use RO only to pass the FDB address parameter. Any other use of RO when you issue the 
OPEN$ macro will fail. 
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CLOSE$—Close Specified File 


When the processing of a file is completed, you must close the file by issuing the CLOSE$ macro. 
The CLOSE$ operation performs the following housekeeping functions: 


1 Waits for all I/O operations in progress for the file to be completed (multibuffered record I/O 
only) 


2 Ensures that the FSR block buffer, which contains data for an output file, is completely written 
if it is partially filled (record I/O only) 


By default, truncates the file being closed 

Deaccesses the file 

Releases the FSR block buffer or buffers allocated for the file (record I/O only) 
Prepares the FDB for subsequent use by clearing appropriate FDB offset locations 


Calls an optional user-coded and user-specified error-handling routine if an error condition is 
detected during the CLOSE$ operation 

Note that I/O does occur in items 1 and 2. Therefore, your program should include error processing 
for CLOSE$ calls as it would for calls to PUT$. 


If you issue a CLOSE$ when a file is already closed, a success status code results. It is not an 
error if you close a file that is already closed. The format of the CLOSE$ macro is shown next. 


CLOSES fdb,err 


Parameters 
fdb 
Specifies a symbolic value of the address of the associated FDB. 


err 
Specifies the symbolic address of a user-coded, optional error-handling routine. 
Examples 

CLOSES #FDBIN, CLSERR 


Shows an explicit declaration for the relevant FDB, and the symbolic address of a user-coded 
error-handling routine to be entered if the CLOSE$ operation is not completed successfully. 


CLOSES ,CLSERR 
CLOSE$ RO 


Assume that RO currently contains the address of the appropriate FDB. 


GET$—Read Logical Record 


The GET$ macro reads logical records from a file. After a GET$ operation, the next record buffer 
descriptors in the FDB always identify the record just read; that is, offset location F NRBD+2 
contains the address of the record just read, and offset location F.NRBD contains the size of that 
record (in bytes). This is true of GET$ operations in both move and locate mode. 


In move mode, a GET$ operation moves a record to your task’s record buffer (as defined by the 
current contents of F URBD+2 and FURBD), and the address and size of that record are then 
returned to the next record buffer descriptors in the FDB (F NRBD+2 and F.NRBD). 
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In locate mode, if the entire record resides within the file storage region (FSR) block buffer, then 
the address and the size of the record just read are returned to the next record buffer descriptors 
(F NRBD+2 and FEF NRBD). If, on the other hand, the entire record does not reside within the FSR 
block buffer, then that record is moved piecemeal into your task’s record buffer, and the address of 
your task’s record buffer and the size of the record are returned to offset locations F NRBD+2 and 
F.NRBD, respectively. 


After returning from a GET$ operation in locate mode, regardless of whether moving the record 
was necessary, F. NRBD+2 always contains the address of the record just read, and F. NRBD always 
contains the size of that record. 


If the record read was a sequenced record, the sequence number is stored in F.SEQN regardless of 
whether the GET$ was in move mode or locate mode. 


GET$ operations are fully synchronous; that is, record I/O operations are completed before control 
is returned to your program. 


Specific FDB requirements for GET$ operations are presented in Section 3.9.2. 


Format of GET$ Macro 


The format of the GET$ macro is shown next. 
GET$ _ fdb,urba,urbs,err 


Parameters 


fdb 
Specifies a symbolic value of the address of the associated FDB. 


urba 


Specifies the symbolic address of your task’s record buffer that is to be used for record I/O 
operations in move or locate mode. When specified, this parameter initializes FDB offset location 
F.URBD+2. 


urbs 


Specifies a numeric value that defines the size (in bytes) of your task’s record buffer. This 
parameter determines the largest record that can be placed in your task’s record buffer in move or 
locate mode. When specified, this parameter initializes offset location F URBD in the associated 
FDB. 


err : 
Specifies the symbolic address of an optional error-handling routine, which you coded. 


If neither the urba nor the urbs parameter is specified in the GET$ macro, FCS assumes that 
these requisite values have been supplied previously through the FDRC$A, the FDRC$R, or the 
generalized OPEN$x macro. Any resulting nonzero values in offset locations FURBD+2 and 
F.URBD are used as the address and the length, respectively, of your task’s record buffer. 


If either of the following conditions occurs during record I/O operations, FCS returns an error 
indication (IE.RBG) to offset location FERR of the FDB, which indicates an illegal record size: 


¢ In move mode, the record size exceeds the limit specified in offset location F URBD. 


e In locate mode, the record size exceeds the limit specified in offset location F.URBD, and the 
record must be moved because it crosses block boundaries. 
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In both move and locate mode, only data up to the amount specified in F. URBD is placed in your 
task’s buffer. The next GET$ begins reading at the beginning of the next record. 


The statements listed in the examples at. the end of this section show how the GET$ macro may be 
used in a program. 


Note 


You can use RO only to pass the FDB address. Any other use of RO when you issue the GET$ 
macro will fail. 


Examples 
GETS RO,,,ERROR 


Assumes the address of the desired FDB is present in RO. Note that the next two parameters, 
that is, your task’s record buffer address (urba) and your task’s record buffer size (urbs), are 
null. In this case, FCS assumes that the appropriate values for FDB offset locations F.URBD+2 
and F.URBD, respectively, have been specified previously in the FDRC$A, the FDRC$R, or the 
generalized OPEN$x macro. The final parameter in the string is the symbolic address of a 
user-coded error-handling routine. 


GETS , #RECBUF, #25., ERROR 


Assumes that RO contains the address of the desired FDB. Explicit parameters then define the 
address and the size, respectively, of your task’s record buffer and an error handler, which you 
coded. 


GETS #INFDB 
Shows a GET$ macro in which only the address of the FDB is specified. 


The FDB Relevant to GET$ Operations 


The following sections summarize the essential aspects of GET$ operations in move and locate 
mode with respect to the associated FDB. 


The following text focuses on whether your task’s record buffer is required under certain conditions. 
In this regard, you should recall that your task’s record buffer descriptors, that is, the urba and 
the urbs parameters, may be specified in the FDRC$A, the FDRC$R, or the generalized OPEN$x 
macro, as well as the I/O-initiating GET$ macro. These parameters must be present in the GET$ 
macro (to appropriately initialize the FDB) only if they were not previously supplied through other 
available means. 


If operating in random access mode, the number of the record to be read is maintained by FCS in 
offset locations FRCNM and F.RCNM+2 of the associated FDB. FCS increments this value after 
each GET$ or GET$R operation to point to the next record in the FSR block buffer. 


Thus, unless your task alters the values in locations F.RCNM and F.RCNM+2 before each issuance 
of the GET$ or GET$R macro call, the next record in sequence is read. Your specified record buffer 
size (that is, the urbs parameter) always determines the largest record that can be read during a 
GETS$ operation. 
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3.9.2.1 GET$ Operations in Move Mode 
With respect to GET$ operations in move mode (refer to Chapter 1 for information on move mode), 
the following generalization applies. If records are always moved to the same record buffer in your 
task, the urba and urbs parameters need be specified only in the initial GET$ macro. Alternatively, 
these values may be specified beforehand through any available means identified previously, for 
initializing your task’s record buffer descriptor cells in the FDB. In any case, offset locations 
F.URBD+2 and F.URBD remain appropriately initialized for all subsequent GET$ operations in 
move mode that involve the same record buffer in your task. 


3.9.2.2 GET$ Operations in Locate Mode 
In performing GET$ operations in locate mode (refer to Chapter 1 for information on locate mode), 
you should take the following information into account: 


NOTE: In the following text, reference is made to the FSR block buffer. By default, the 
block size that FCS uses is equivalent to the buffer size of the device on which the file is 
opened. If big buffering is enabled (that is, an ovbs parameter value is specified in the 
FDBF$x macro, as described in Chapter 2) the FSR block buffer will be more than one 
block long. As a result, it may not be necessary to move a record even though it crosses 
block boundaries because both blocks are currently within the FSR block buffer space. 
Thus, moves are only necessary when the record crosses a buffer boundary, which is not 
necessarily the same as a block boundary in a big-buffered file. 


e If fixed-length records are to be processed, and if they fit evenly within the FSR block buffer, 
your task’s record buffer descriptors need not be present in the associated FDB. 


e If fixed-length records that do not fit evenly within the FSR block buffer are to be processed, or 
if variable-length records are to be processed, your task’s record buffer descriptors need not be 
present in the FDB, provided that the file being processed exhibits the attribute of records not 
being allowed to cross block boundaries (FD.BLK). 


The property of records not crossing block boundaries is established as the file is created. 
Specifically, if offset location F.RATT in the FDB is initialized with FD.BLK prior to the time 
the file is created, the records in the resulting file are not allowed to cross buffer boundaries. 


For an existing file, the file-attribute section of the file header block is read when the file is 
opened; thus, all attributes of that file are made known to FCS, including whether records 
within that file are allowed to cross block boundaries. 


The design of FCS requires you to use your task’s record buffer only in the event that records 
(either fixed or variable in length) cross buffer boundaries. 


¢ If a GET$ operation is performed in locate mode, and the record is contained entirely within 
the FSR block buffer, the address of the record within the FSR block buffer and the size of 
that record are returned to the associated FDB in offset locations FNRBD+2 and FNRBD, 
respectively. However, if that record crosses buffer boundaries, it is moved to your task’s record 
buffer. In this case, the address of your task’s record buffer and the size of the record are 
returned to offset locations F NRBD+2 and F. NRBD, respectively. 


In summary, if the potential exists for crossing buffer boundaries during GET$ operations in locate 
mode, then your task’s record buffer descriptors must be supplied through any available means to 
appropriately initialize offset locations F URBD+2 and F.URBD in the associated FDB. 
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GET$R—Read Logical Record in Random Mode 


The GET$R macro reads fixed-length records from a file in random mode. Thus, by definition, 
issuing this macro requires that you be familiar with the structure of the file to be read and, 
furthermore, that you be able to specify precisely the number of the record to be read. 


The GET$ and GET$R macros are identical, except that the parameter list of GET$R includes 
the specification of the desired record number. If the desired record number is already present in 
the FDB (at offset locations FRCNM and F.RCNM+2), then GET$ may be used. If, however, the 
record access byte in the FDB (offset location F.RACC) has not been initialized for random access 
operations with FD.RAN in the FDRC$A, the FDRC$R, or the generalized OPEN$x macro, then 
neither GET$ nor GET$R will read the desired record. 


The GET$R macro takes two more parameters in addition to those specified in the GET$ macro. 
GET$R_fdb,urba,urbs, Ircnm,hrenm,err 


Parameters 


ircnm 

Specifies the low-order 16 bits of the number of the record to be read. This value, which must 
be specified, is stored in offset location F RCNM+2 in the FDB. The GET$R macro call seldom 
requires more than 16 bits to express the record number. A logical record number up to 65,53619 
may be specified through this parameter. If this parameter is not sufficient to completely express 
the magnitude of the record number, the hrcnm parameter must also be specified. 


hrenm 

Specifies the high-order 15 bits of the number of the record to be read. This value is stored in FDB 
offset location F.RCNM. If specified, the combination of this parameter and the Ircnm parameter 
determines the number of the desired record. Thus, an unsigned value having a total of 31 bits of 
magnitude may be used in defining the record number. 


If this parameter is not specified, offset location F.RCNM retains its initialized value of 0. 


If you use F.RCNM to specify a desired record number for any given GETS$R operation, this cell 
must be cleared before issuing a subsequent GET$R macro that requires 16 bits or less to express 
the desired record number; otherwise, any residual value in F.RCNM yields an incorrect record 
number. 


If the Ircnm and hrcnm parameters are not specified in a subsequent GET$R macro, the next 
sequential record is read because the record number in offset locations F RCNM+2 and F RCNM 
is increased by 1 with each GET$ operation. In the case of the first GET$R, after opening the 
file, record number 1 is read because the record number has been initialized to 0 by the OPEN 
macro. If a record other than the next sequential record is to be read, you must explicitly specify 
the number of the desired record. 


The statements listed at the end of this section represent the use of the GET$R macro. 


Note 


RO can be used only to pass the FDB address parameter. Any other use of RO when issuing the 
GET$R macro will fail. 
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Examples 
GETSR #INFDB, #RECBUF, #160., #1040., , ERROR 


Expresses, through the first of two available fields for this purpose, the desired number to be read, 
that is, 1040,9. The second field is not required and is therefore reflected as a null specification. 
The number of the desired record to be read, that is, 104019, is expressed through the first of two 
available fields; the second field is not required and is therefore refle cted as a null specification. 


GETSR #FDBADR, #RECBUF, #160.,R3 


Reflects the use of general register 3 in specifying the logical record number. This register, or any 
other location so used, must be preset with the desired record number before issuing the GET$R 
macro. - 


GET$S—Read Logical Record in Sequential Mode 


The GET$S macro reads logical records from a file in sequential mode. Although the routine 
invoked by the GET$S macro requires less memory than that invoked by GET$ (see Section 3.9), 
GET$S has the same format and takes the same parameters. The GET$S macro is specifically for 
use in an overlaid environment in which the amount of memory available to the program is limited 
and files are to be read in strictly sequential mode. 


If both GET$S and PUTS$S are to be used by the program, note that the savings in memory usage 
over GET$ and PUT$ can be realized only if GET$S and PUT$S are placed on different branches 
of the overlay structure. 


PUT$—Write Logical Record 


The PUT$ macro writes logical records to a file. If operating in random access mode, the number 
of the record to be written is maintained by FCS in offset locations F. RCNM and F.RCNM+2 of 
the associated File Descriptor Block (FDB). File Control Services (FCS) increases this value by 1 
after each PUT$ or PUT$R operation to point to the next sequential record position. Thus, unless 
your program alters this value before issuing another PUT$ or PUT$R operation, the next record 
in sequence is written. . 


For PUT$ operations, offset locations F NRBD+2 and F.NRBD in the associated FDB must contain 
the address and the size, respectively, of the record to be written. The distinction between move 
mode and locate mode for PUT$ operations relates to the building or the assembling of the data 
into a record. Specifically, in move mode the record is built in a buffer of your choice. This 
buffer is not necessarily your task’s record buffer previously described in the context of record 
I/O operations. In other words, you can build records in an area of a program apart from that 
normally defined by your task’s record buffer descriptors in the FDB (F.URBD+2 and F.URBD). 
In this case, you specify the address of the record buffer so used and the size of the record in the 
PUT$ macro, and the record thus built is then moved into the FSR block buffer. 


In locate mode, however, the record is built at the address specified by the contents of offset 
location F. NRBD+2, and only the record size need be specified in the PUT$ macro. Then, if the 
record so built is not already in the FSR block buffer, it is moved there as the PUT$ operation is 
performed. 


If the records in the file are sequenced records, the field FSEQN in the FDB contains the sequence 
value, which you can modify. 


PUT$ operations are fully synchronous; that is, record I/O operations are completed before control 
is returned to your task’s program. 
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A random PUT$ operation in locate mode requires the use of the .POSRC routine. This operation 
is described in detail in Chapter 4. Specific FDB requirements for PUT$ operations are presented 
in Section 3.12.2. 


Format of PUT$ Macro 
The format of the PUT$ macro is shown next. 


PUT$  fdb,nrba,nrbs,err 


Parameters 


fdb 
Specifies a symbolic value of the address of the associated FDB. | 


nrba 


Specifies the symbolic address of the next record buffer, that is, the address of the record to be 
PUT$. This parameter initializes FDB offset location FNRBD+2. 


nrbs 


Specifies the size of the next record buffer, that is, the length of the record to be PUT$. This 
parameter initializes FDB offset location F NRBD. 


err 
Specifies the symbolic address of an optional error-handling routine, which you coded. 


The examples listed at the end of this section show how the PUT$ macro may be used in a 
program. 


Note 


RO can only be used to pass the FDB address parameter as shown in the third example; it cannot 
be used to pass any other parameter in the PUT$ macro. 


Examples 
PUTS #FDBADR, ,,ERRRT 


Shows the next record buffer address (nrba parameter) and the next record buffer size (nrbs 
parameter) are null. These null specifications imply that the current values in offset locations 
F.NRBD+2 and F.NRBD of the associated FDB are suitable to the current operation. Note also 
that fixed-length records could also be written in locate mode by issuing this macro. 


PUTS ,, #160.,ERRRT 


Contains null specifications in the first two parameter fields, assuming that RO currently contains 
the address of the associated FDB and that variable-length records are to be written to the file. 


PUTS RO 


Specifies only the address of the FDB; all other parameter fields are null. 
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The FDB Relevant to PUT$ Operations 


This subsection highlights aspects of PUT$ operations in move and locate mode that have a bearing 
on the associated FDB. 


The conditions under which your task’s record buffer is or is not used are summarized. As is 

the case for GET$ operations, if your task’s record buffer is required for PUT$ operations, the 
buffer descriptors (that is, the urba and urbs parameters) may be supplied to the associated 
FDB through the FDRC$A, the FDRC$R, or the generalized OPEN$x macro. In any case, offset 
locations F URBD+2 and F.URBD must be appropriately initialized if PUT$ operations require the 
utilization of your task’s record buffer. Note, however, that PUT$ operations in move mode never 
require a record buffer. 


If your task’s record buffer is required, the specified size of that buffer (that is, the urbs parameter) 
always determines the size of the largest record that can be written to the specified file. 


Whether in move or locate mode, a PUT$ operation uses the information in offset locations 
F.NRBD+2 and F.NRBD, that is, the next record buffer descriptors, to determine whether the 
record must be moved into the FSR block buffer. In the event that the record does have to be 
moved, and the size of that record is such that it cannot fit in the space remaining in the FSR 
block buffer, one of the following two possible operations is performed: 


e If records are allowed to cross block boundaries, then the first part of the record is moved into 
the FSR block buffer, thereby completing a virtual block. That block buffer is then written out 
to the volume, and the remaining portion of the record is moved into the beginning of the next 
FSR block buffer. 


¢ If records are not allowed to cross block boundaries (because of the file attribute FD.BLK 
specified in the associated FDB), then the FSR block buffer is written out to the volume, as is, 
and the entire record is moved into the beginning of the next FSR block buffer. 


3.12.2.1 PUT$ Operations in Move Mode 
A PUT$ operation in move mode (see Chapter 2) is driven by specifying in each PUT$ macro the 
address and the size of the record to be written. Then, as the PUT$ operation is performed, FCS 
moves the record into the appropriate area of the FSR block buffer. 


In summary, the following generalizations apply for PUT$ operations in move mode: 


¢ Your task’s record buffer descriptors need not be present in the FDB because the programmer is 
dynamically specifying the address and the length of the record to be written at each issuance 
of a PUT$ macro. The values specified dynamically update offset locations FNRBD+2 and 
F.NRBD in the associated FDB. 


e If the file consists of fixed-length records, then the generalized OPEN$x macro (see Section 3.1) 
initializes offset location F NRBD with the appropriate.record size, as defined by the contents of 
offset location F.RSIZ. Thus, the size of the record need not be specified as the nrbs parameter 
in any PUT$ macro involving this file. 


e If the variable-length records are being used during a PUT$ operation, the size of each record 
must be specified as the nrbs parameter in each PUT$ macro call involving this file, thus 
setting offset location F.NRBD to the appropriate record size. 
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3.12.2.2 PUTS$ Operations in Locate Mode 
Your task’s record buffer is required for PUT$ operations in locate mode (see Chapter 2) only when 
the potential exists for records to cross buffer boundaries. If there is insufficient space in the FSR 
block buffer to accommodate the building of the next record, you must provide a buffer in your 
task’s memory space to build that record. 


When a file is initially opened for PUT$ operations in locate mode, FCS sets up offset location 
F.NRBD+2 to point to the area in the FSR block buffer where the next record is to be built. Then, 
each PUT$ operation thereafter in locate mode updates the address value in this cell to point 

to the area in the FSR block buffer where the next record is to be built. Thus, after each PUT$ 
‘operation in locate mode, F NRBD+2 points to the area where the next record is to be built. This 
logic dictates whether your record buffer is required in locate mode. 


The following generalizations apply: 


NOTE: In the following discussion, reference is made to the FSR block buffer. By 
default, the block size that FCS uses is equivalent to the buffer size of the device on 
which the file is opened. If big buffering is enabled (that is, an ovbs parameter value is 
specified in the FDBF$x macro, as described in Chapter 2) the FSR block buffer will be 
more than one block long. As a result, it may not be necessary to move a record even 
though it crosses block boundaries because both blocks are currently within the FSR 
block buffer space. Thus, moves are only necessary when the record crosses a buffer 
boundary, which is not necessarily the same as a block boundary in a big-buffered file. 


e If your task is performing a PUT$ operation for fixed-length records and they fit evenly within 
the FSR block buffer, your task’s record buffer is not required. 


¢ Ifa fixed-length record crosses block boundaries, your task’s record buffer descriptors must be 
present in offset locations F URBD+2 and F.URBD of the associated FDB. In this case, after 
FCS determines that the record cannot fit in the FSR block buffer, FCS sets offset location 
F.NRBD+2 to point to your task’s record buffer. Then, when the record is processed with the 
PUT$ operation, it is moved from your record buffer to the FSR block buffer. 


¢ Ifa variable-length record is processed with the PUT$ operation, the potential exists for 
crossing block boundaries. In this case, your task’s record buffer descriptors must be present 
in offset locations F URBD+2 and F.URBD of the associated FDB. Moreover, the size of each 
variable-length record must be specified as the nrbs parameter in each PUT$ macro. 


Determining if FCS points offset location FNRBD+2 to the FSR block buffer for the PUT$ 
operation or to your task’s record buffer is based on whether there is enough room in the FSR 
block buffer to accommodate the record. 


Because the records are variable in length, you can assume that the largest possible record 
is PUT$, as defined by the size of your task’s record (F.URBD). Thus, if a record of this 
defined size cannot fit in the space remaining in the FSR block buffer, FCS sets offset location 
F.NRBD+2 to point to your task’s record buffer. 


Each PUT$ operation in locate mode sets up the FDB for the next PUT$ operation. The specified 
record size is used by FCS as the worst-case condition in determining whether sufficient space 
exists in the FSR to build the next record. 


If variable-length records are being processed that are shorter than the largest defined record 
size, FCS may move records unnecessarily from your task’s record buffer to the FSR block buffer. 
For example, assume that your task has allocated a 132-byte record buffer and further, that 

the available remaining space in the FSR block buffer is less than 132 bytes. In this case, FCS 
continues to point to your task’s record buffer for PUT$ operations, even if you continue to perform 
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PUT$ operations with short (10- or 20-byte) records. Thus, some unavoidable movement of records 
takes place in locate mode. 


If the largest record that you intend to process with the PUT$ operation is 80 bytes, for example, 
then the largest defined record size should not be specified as 132 bytes (or any length larger than 
that intended to be processed with the PUT$ operation). Aside from having to allocate a smaller 
record buffer in your task, PUT$ operations in locate mode are more efficient if this precaution 

is observed. Exercising care in this regard reduces the tendency to move records from your task’s 
record buffer to the FSR block buffer when they might otherwise be built directly in the FSR block 
buffer. 


PUT$R—Write Logical Record in Random Mode 


The PUT$R macro writes fixed-length records to a file in random mode. As noted in Section 3.10, 
the GET$R macro, operations in random access mode require you to be very familiar with the 
contents of such files. The PUT$R macro also relies entirely on you to specify the number of the 
record before a specified PUT$ operation can be performed. Because the usual purpose of a PUT$R 
operation is to update known records in a file, it is assumed that you also know the number of such 
records within the file. 


The PUT$ and PUT$R macros are identical, except that PUT$R allows the specification of the 
desired record number. If the desired record number is already present in the FDB (at offset 
locations F.RCNM and F.RCNM+2), then PUT$ and PUT$R may be used interchangeably. 
However, if the record access byte in the FDB (offset location F.RACC) has not been initialized 
for random access operations with FD.RAN in the FDRC$A, the FDRC§$R, or the generalized 
OPEN$x macros, then neither PUT$ nor PUT$R will write the desired record. 


The PUT$R macro takes two more parameters in addition to those specified in the PUT$ macro. 
PUT$R = fdb,nrba,nrbs, Ircnm,hrenm, err 


Parameters 


Ircnm 

Specifies the low-order 16 bits of the number of the record to be processed. This parameter serves 
the same purpose as the corresponding parameter in the GET$R macro (see Section 3.10), except 
that it identifies the record to be written. 


hrenm 

Specifies the high-order 15 bits of the number of the record to be processed. This parameter serves 
the same purpose as the corresponding parameter in the GET$R macro, except that it identifies 
the record to be written. 


If this parameter is not specified, offset location F RCNM retains its initialized value of 0. 


If F.RCNM is used in expressing a desired record number for any given PUT$R operation, you 
must clear this cell before issuing a subsequent PUT$R macro that requires 16 bits or less in 
expressing the desired record number; otherwise, any residual value in F.RCNM results in an 
incorrect record number. 


The Ircnm and hrenm parameters initialize offset locations F RCNM+2 and F.RCNM, respectively, 
in the associated FDB. If these values are not specified in a subsequent PUT$R macro, the next 
sequential record is written because FCS increases the record number by 1 in these cells after 
each PUT$ operation. In the case of the first PUT$R after opening the file, record number 1 is 
written. Note that this is true even if the file has been opened for an append operation (OPEN$A 
If a record other than the next sequential record is to be written, you must explicitly specify the 
number of the desired record. 
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Examples listed at the end of this section show how the PUT$R macro may be used in a program. 


Notes 


1 Arandom mode PUT$R operation executed in locate mode must be preceded by a call to 
.POSRC. Because locate mode allows you to store data directly into the block buffer, the 
file must be positioned so that the desired record position is in fact in the block buffer. See 
Chapter 4 for further details. 


2 You can use RO only to pass the FDB address. Any other use of RO when you issue the PUT$R 
macro will fail. 


Examples 
PUTSR #OUTFDB, #RECBUF, , #12040., , ERRLOC 


Indicates that you are specifying the address of the record. You can determine this by the presence 
of RECBUF as the next record buffer address (nrba). Although specifying this address repeatedly 
is unnecessary, it is not invalid. Normally, a buffer address is specified dynamically because other 
PUT$ macro calls may be referencing different areas in memory; thus, the address of the record 
must be explicitly specified in each PUT$ macro. Note also that the next record buffer size (nrbs) 
parameter is null, because this parameter is required only in the case of writing variable-length 
records. Also, the second of the two available parameters for defining the record number is null. 


PUTSR #FDBADR, #RECBUF, , R4 
PUTSR #FDBADR, #RECBUF, , LRN 


Indicates that R4 and a memory location (LRN) are used to specify the logical record number. Such 
a specification assumes that you have preset the desired record number in the referenced location. 


PUT$S—Write Logical Record in Sequential Mode 


The PUT$S macro writes logical records to a file in sequential mode. Although the routine invoked 
by the PUT$S macro requires less memory than that invoked by PUT$ (see Section 3.12), PUT$S 
has the same format and takes the same parameters. The PUT$S macro is specifically for use in 
an overlaid environment in which the amount of memory available to the program is limited and 
files are to be written in strictly sequential mode. 


If both GET$S and PUT$S are to be used by the program, the savings in memory utilization over 
GET$ and PUT$ are realized only if GET$S and PUT$S are placed on different branches of the 
overlay structure. 


READ$—Read Virtual Block 


The READ$ macro reads a virtual block of data from a block-oriented device (for example, a 
magnetic tape, a disk, or DECtape). In addition, if certain optional parameters are specified in the 
READ$ macro, status information is returned to the I/O status block (IOSB) (see Chapter 2) or 
the program traps to an asynchronous system trap (AST) service routine, which you coded, at the 
completion of block I/O operations (see Chapter 2). 


In issuing the READ$ (or WRITE$) macro, you are responsible for synchronizing all block I/O 
operations. For this reason, the WAIT$ macro is provided (see Section 3.17), which enables you 
to suspend program execution until a specified READ$ or WRITE$ operation has been completed. 
It is important, however, that you test the contents of FERR in the File Descriptor Block (FDB) 
for error codes immediately after issuing the READ$ or WRITE$ call as well as on return from 
the WAIT$ call. When errors occur during multiple-block transfers, the second word of the IOSB 
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will contain the number of bytes transferred before the error occurred. The READ$ or WRITE 
operations can return error codes distinct from those that can be present on completing a WAIT$ 
operation. For example, IE.EOF will be returned upon completion of the READ$ operation but not 
upon completion of the WAIT$ operation. 


When your task issues the WAIT$ macro with a READ$ (or WRITE$) macro, you must ensure that 
the event flag number and the IOSB address specified in both macro calls are the same. 


When the WTSE$ macro waits for I/O completion, the issuing task must check I/O errors by 
examining the IOSB (defined by the task). (The IOSB is described in Chapter 2.) When WTSE$ is 
used, File Control Services (FCS) will not return a completion code to offset F.ERR in the FDB. 


Format of READ$ Macro 


Note in the following format that the parameters of the READ$ macro are identical to those of 
the FDBK$A or the FDBK$R macro, with the exception of the fdb and err parameters. Certain 
FDB parameters may be set at assembly time (FDBK$A), initialized at run time (FDBK$R), or 
set dynamically by the READ$ macro. Certain information must be present in the FDB before 
the specified READ$ (or WRITE$) operation can be performed. These requirements are noted in 
Section 3.15.2. 


READ$  fdb,bkda,bkds,bkvb, bkef, bkst. bkdn,err 


Parameters 


fdb 
Specifies a symbolic value of the address of the associated FDB. 


bkda 

Specifies the symbolic address of the block I/O buffer in your program. This parameter need not be 
specified if offset location F. BKDS+2 has been previously initialized through either the FDBK$A or 
the FDBK$R macro. 


bkds 

Specifies the size (in bytes) of the virtual block to be read. This parameter need not be specified if 
offset location F.BKDS has been previously initialized through either the FDBK$A or the FDBK$R 
macro. The maximum block size that may be specified for file-structured devices is 32,256 bytes. 


bkvb 

Specifies the symbolic address of a two-word block in your program containing the number of the 
virtual block to be read. This parameter causes offset locations F. BKVB and F.BKVB+2 to be 
initialized with the virtual block number; F BKVB+2 contains the low-order 16 bits of the virtual 
block number, and F. BKVB contains the high-order 15 bits. 


As noted in connection with the FDBK$A macro described in Chapter 2, assembly-time 
initialization of the virtual block number in the FDB is ineffective because the generalized OPEN$x 
macro sets the virtual block number in the FDB to 1. 


The virtual block number can be made available to FCS only through the FDBK$R macro or the 
I/O-initiating READ$ (or WRITE$) macro after the file has been opened. The virtual block number 
is created as described in Chapter 2. 


.The READ$ function checks the specified virtual block number to ensure that it does not reference 


a nonexistent block, that is, a block beyond the end of the file. If the virtual block number 
references nonexistent data, an end-of-file (IE.EOF) error indication is returned to offset location 
F.ERR of the associated FDB; otherwise, the READ$ operation proceeds normally. If the total 
number of bytes goes beyond the end of the file, then as many blocks as exist are read and the byte 
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count of the shortened transfer is returned in I/O STATUS+2. No error condition occurs, so you 
must check the count on each READ. An end-of-file indication is returned only if no blocks can be 
read. 


If the virtual block number is not specified through any of the available means identified already, 
sequential operation results by default, beginning with virtual block number 1. The virtual block 
number is incremented by the number of blocks read after each READ$ operation is performed. 


bkef 

Specifies the event flag number to be used for synchronizing block I/O operations. This event flag 
number is used by FCS to signal the completion of the specified block I/O operation. The event 
flag number, which may also be specified in either the FDBK$A or the FDBK$R macro, initializes 
FDB offset location F BKEF; if specified, this parameter need not be included in the READ$ (or 
WRITE$) macro. 


If this optional parameter is not specified through any available means, event flag 3219 is used by 
default. The function of an event flag is discussed in further detail in Chapter 2. 


bkst 


Specifies the symbolic address of the IOSB in your task (see Chapter 2). This parameter, which 
initializes offset location F.BKST, is optional. The IOSB is filled in by the system when the 
requested block I/O transfer is completed, indicating the success or failure of the requested 
operation. 


The address of the IOSB may also be specified in either the FDBK$A or the FDBK$R macro. If the 
address of this 2-word structure is not supplied to FCS through any of the available means, status 
information cannot be returned to your program. Regardless, the event flag specified through the 
bkef parameter is set to indicate block I/O completion, but, without an IOSB, your program must 
assume that the operation (for example, READ$ or WRITE$) was successful. 


bkdn 


Specifies the symbolic entry point address of an AST service routine (see Chapter 2). If this 
parameter is specified, a trap occurs upon completion of the specified READ$ (or WRITE$) 
operation. This optional parameter initializes offset location F.BKDN. This address value may also 
be made available to FCS through either the FDBK$A or the FDBK$R macro, and, if specified, 
need not be present in the READ$ (or WRITE$) macro call. 


If the address of an AST service routine is not specified through any available means, no AST trap 
occurs at the completion of block I/O operations. 


err 
Specifies the symbolic address of an optional error-handling routine, which you coded. 


The examples listed at the end of this section represent READ$ macros that may be issued to 
accomplish a variety of operations. 


Note 


You can use RO only to pass the FDB address. Any other use of RO when you issue the READ$ 
macro will fail. 


Examples 
READ$ RO 


Assumes that RO contains the address of the associated FDB. Also, all other required FDB 
initialization has been accomplished through either the FDBK$A or the FDBK$R macro call. 


READS +#INFDB,,,,,,,ERRLOC 
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Shows an explicit declaration of the associate FDB and includes the symbolic address of an 
error-handling routine, which you coded. 


READS RO, #INBUF, #BUFSIZ, , #22., #IOSADR, #ASTADR, ERRLOC 


Shows that RO again contains the address of the associated FDB. The block buffer address and 
the size of the block are specified next in symbolic form. The address of the 2-word block in your 
program containing the virtual block number is not specified, as indicated by the additional comma 
in the parameter string. The event flag number, the address of the IOSB, and the address of the 
AST service routine then follow in order. Finally, the symbolic address of an optional error routine 
is specified. 


READS #INFDB, #INBUF, #BUFSIZ, #VBNADR 


Reflects, as the last parameter in the string, the symbolic address of the 2-word block in your 
program containing the virtual block number. 


The FDB Relevant to READ$ Operations 


The READ$ macro requires that the associated FDB be initialized with certain values before it 
can be issued. You can specify these values through either the FDBK$A or the FDBK$R macro, or 
they may be made available to the FDB through the various parameters of the READ$ macro. The 
following values must be present in the FDB to enable READ$ operations to be performed: 


¢ The block buffer address (in offset location F BKDS+2) 
¢ The block byte count (in offset location F.BKDS) 
¢ The virtual block number (in offset locations F BKVB+2 and F.BKVB) 


NOTE: When either READ$ or WRITES operations are performed, FCS maintains the 
end-of-file (EOF) block number field (F.EFBK) and clears the first free byte in the last 
block field (F.FFBY) in the FDB. During a READ$ operation, EOF is determined by the 
EOF block number field in F.EFBK. If desired, you can modify F.FFBY before closing the 
file by using the CLOSE$ macro call. 


WRITE$—Write Virtual Block 


The WRITE$ macro is issued to write a virtual block of data to a block-oriented device (for 
example, magnetic tape, disk, DECtape, or DECtape II). Like the READ$ macro, if certain optional 
parameters are specified in the WRITE$ macro, status information is returned to the IOSB (see 
Chapter 2), and, at the completion of the I/O transfer, the program traps to an AST service routine 
that is supplied to coordinate asynchronous block I/O operations (see Chapter 2). 


Whether or not you supply the address of an AST service routine and an event flag number, you 
are responsible for synchronizing all block I/O processing. The WAIT$ macro can be issued with 
the WRITE$ macro to suspend program execution until a program-dependent I/O transfer has been 
completed. When the WAIT$ macro is used for this purpose, the event flag number and the IOSB 
address in both macros must be the same. Again, as with READ$ operations, you should check 
for an error code immediately following the WRITE$ macro as well as on return from the WAIT$ 
macro. 
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Format of WRITES Macro 


The WRITE$ macro takes the same parameters as the READ$ macro. The bkvb parameter 
represents the symbolic address of a 2-word block containing the number of the virtual block to be 
written. The virtual block number is incremented after each WRITE$ operation is performed. 


WRITES __fdb,bkda,bkds, bkvb, bkef, bkst, bkdn, err 


Parameters 


fdb 
Specifies a symbolic value of the address of the associated FDB. 


bkda 

Specifies the symbolic address of the block I/O buffer in your program. This parameter need not be 
specified if offset location F. BKDS+2 has been previously initialized through either the FDBK§A or 
the FDBK$R macro. 


bkds 

Specifies the size (in bytes) of the virtual block to be written. This parameter need not be specified 
if offset location F. BKDS has been previously initialized through either the FDBK$A or the 
FDBK$R macro. The maximum block size for file-structured devices is 32,256 bytes. 


bkvb 

Specifies the symbolic address of a two-word block in your program containing the number of the 
virtual block to be written. This parameter causes offset locations F.BKVB and F.BKVB+2 to be 
initialized with the virtual block number, F.BKVB+2 contains the low-order 16 bits of the virtual 
block number, and F.BKVB contains the high-order 15 bits. 


As noted in connection with the FDBK$A macro described in Chapter 2, assembly-time 
initialization of the virtual block number in the FDB is ineffective because the generalized OPEN$x 
macro sets the virtual block number in the FDB to 1. 


The virtual block number can be made available to FCS only through the FDBK$R macro or the 
1/O-initiating WRITE$ (or READ$) macro after the file has been opened. The virtual block number 
is created as described in Chapter 2. 


If the virtual block number is not specified through any of the available means identified already, 
sequential operation results by default, beginning with virtual block number 1. The virtual block 
number is incremented by the number of blocks written after each WRITE$ operation is performed. 


bkef 

Specifies the event flag number to be used for synchronizing block I/O operations. This event flag 
number is used by FCS to signal the completion of the specified block I/O operation. The event flag 
number, which may also be specified in either the FDBK$A or the FDBK$R macro, initializes FDB 
offset location F.BKEF; if specified, this parameter need not be included in the WRITE$ macro. 


If this optional parameter is not specified through any available means, event flag 329 is used by 
default. The function of an event flag is discussed in further detail in Chapter 2. 


bkst 


Specifies the symbolic address of the IOSB in your task (see Chapter 2). This parameter, which 
initializes offset location F.BKST, is optional. The IOSB is filled in by the system when the 
requested block I/O transfer is completed, indicating the success or failure of the requested 
operation. 
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The address of the IOSB may also be specified in either the FDBK$A or the FDBK$R macro. If the 
address of this 2-word structure is not supplied to FCS through any of the available means, status 
information cannot be returned to your program. Regardless, the event flag specified through the 
bkef parameter is set to indicate block I/O completion, but, without an IOSB, your program must 
assume that the WRITE$ operation was successful. 


bkdn 

Specifies the symbolic entry point address of an AST service routine (see Chapter 2). If this 
parameter is specified, a trap occurs upon completion of the specified WRITE$ operation. This 
parameter, which is optional, initializes offset location F. BKDN. This address value may also be 
made available to FCS through either the FDBK$A or the FDBK$R macro, and, if specified, need 
not be present in the WRITE$ macro call. 


If the address of an AST service routine is not specified through any available means, no AST trap 
occurs at the completion of block I/O operations. 


err 
Specifies the symbolic address of an optional error-handling routine, which you coded. 


When this macro is issued, the virtual block number (that is, the bkvb parameter) is checked to 
ensure that it references a block within the file’s allocated space; if it does, the block is written. If 
the specified block is not within the file’s allocated space, FCS attempts to extend the file. If this 
attempt is successful, the block is written; if the attempt is unsuccessful, an error code indicating 
the reason for the failure of the extend operation is returned to the IOSB and to offset location 
F.ERR of the associated FDB. 


If FCS determines that the file must be extended, the actual extend operation is performed 
synchronously. After the extend operation has been successfully completed, the WRITE$ operation 
is queued, and only then is control returned to the instruction immediately following the WRITE$ 
macro. 


The examples listed at the end of this section show how the WRITE$ macro may be used in a 
program. 

Note 

You can use RO only to pass the FDB address. Any other use of RO when you issue the WRITE$ 


macro will fail. 


Examples 
WRITE$ RO 

Specifies only the FDB address and assumes that all other required values are present in the FDB. 
WRITES #OUTFDB, #OUTBUF, #BUFSIZ, #VBNADR, #22. 


Reflects explicit declarations for the FDB, the block buffer address, the block buffer size, the virtual 
block number address, and the event flag number for signaling block I/O completion. 


WRITES RO,,,,#22., #IOSADR, #ASTADR, ERRLOC 


Shows null specifications for three parameter fields, then continues with the event flag number, the 
address of the IOSB, and the address of the AST service routine. Finally, it specifies the address of 
an error-handling routine, which you coded. 
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The FDB Relevant to WRITE$ Operations 


WRITES operations require the presence of the same information in the FDB as READ$ operations 
(see Section 3.15.2). 


WAIT$—Wait-For Block I/O Completion 


The WAIT$ macro, which is issued only with READ$ and WRITE$ operations, suspends program 
execution until the requested block I/O transfer is completed. This macro may be used to 
synchronize a block I/O operation that depends on the successful completion of a previous block I/O 
transfer. 


As noted in Section 3.15, the READ$ macro, you can specify an event flag number through the bkef 
parameter. This event flag number is used during READ$ (or WRITE$) operations to indicate the 
completion of the requested transfer. If desired, you can issue a WAIT$ macro (specifying the same 
event flag number and IOSB address) following the READ$ (or WRITE$) macro. 


The READ$ (or WRITE$) operation is initiated in the usual manner, but the Executive suspends 
program execution until the specified event flag is set, indicating that the I/O transfer has been 
completed. The system then returns information to the IOSB, indicating the success or failure of 
the operation. File Control Services (FCS) then moves the IOSB success or failure indicator into 
offset location F.ERR of the associated File Descriptor Block (FDB). FCS returns with the carry 
condition code in the Processor Status Word (PSW) cleared if the operation is successful, or set if 
the operation is not successful. Task execution then continues with the instruction immediately 
following the WAIT$ macro. 


The system returns the final status of the I/O operation to the IOSB (see Chapter 2) upon 
completion of the requested operation. A positive value (+) indicates successful completion, and a 
negative value (—) indicates unsuccessful completion. 


Event flags are discussed in further detail in Chapter 2. 


Format of WAIT$ Macro 
The format of the WAIT$ macro follows. 
WAITS _ fdb,bkef.bkst,err 


Parameter 


fdb 
Specifies a symbolic value of the address of the associated FDB. 


bkef 
Specifies the event flag number to be used for synchronizing block I/O operations. The WAIT$ 
macro causes task execution to be suspended by invoking the WTSE$ (Wait-for Single Event Flag) 


system directive. This parameter must agree with the corresponding (bkef) parameter in the 
associated READ$ or WRITE$ macro. 


If this parameter is not specified, either in the WAIT$ macro call or the associated READ$ or 
WRITE macro, FDB offset location F BKEF is assumed to contain the desired event flag number, 
as previously initialized through the bkef parameter of the FDBK$A or the FDBK$R macro. 
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bkst 


Specifies the symbolic address of the IOSB in your program (see Chapter 2). Although this 
parameter is optional, if it is specified, it must agree with the corresponding (bkst) parameter 
in the associated READ$ or WRITE$ macro. 


If this parameter is not specified, either in the WAIT$ macro call or the associated READ$ or 
WRITE$ macro, FDB offset location F BKST is assumed to contain the address of the IOSB, 
as previously initialized through the bkst parameter of the FDBK$A or the FDBK$R macro. If 
F.BKST has not been initialized, no information is returned to the IOSB. 


err 
Specifies the symbolic address of an optional error-handling routine, which you coded. 
The examples listed at the end of this section show how the WAIT$ macro can be used in a 
program. 
Note 
You can use RO only to pass the FDB address. Any other use of RO when you issue the WAIT$ 
macro fails. 
Examples 
WAITS RO 


Assumes that RO contains the address of the associated FDB; furthermore, because no flag number 
(bkef parameter) is specified, offset location F. BKEF is assumed to contain the desired event flag 
number. If this cell in the FDB contains 0, event flag number 329 is used by default. 


WAITS  #INFDB, #25. 


Shows an explicit specification of the File Descriptor Block (FDB) address and specifies 2519 as 
the event flag number. Again, in this example, the FDB is assumed to contain the address of the 
IOSB. 


WAITS RO, #25., #IOSTAT 


Shows an explicit specification for the address of the IOSB, which is in contrast to the second 
example. 


WAITS RO, , #IOSTAT, ERRLOC 


Contains a null specification for the event flag number, and, in addition, specifies the address of an 
error-handling routine, which you coded. 


Please note that the WAIT$ macro associated with a given READ$ or WRITE$ operation need not 
be issued immediately following the macro to which it applies. For example, the following sequence 
is typical: 


1 Issue the desired READ$ or WRITE$ macro. 


2 Perform other processing that is not dependent on the completion of the requested block I/O 
transfer. 


3 Issue the WAIT$ macro. 
4 Perform the processing that is dependent on the completion of the requested block I/O transfer. 


When you perform several asynchronous transfers in the same general sequence described 
previously, you must maintain a separate buffer, IOSB, and event flag for each operation. If 
you intend to wait for the completion of a given transfer, the appropriate event flag number and 
IOSB address must be specified in the associated WAIT$ macro. 
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DELET$-—Delete Specified File 


The DELET$ macro causes the directory information for the file associated with the specified FDB 
to be deleted from the appropriate User File Directory (UFD). The space occupied by the file is 
then deallocated and returned for reallocation to the pool of available storage on the volume. 


This macro can be issued for a file that is either open or closed. If issued for an open file, that file 
is then closed and deleted; if issued for a closed file, that file is deleted only if the filename string 
specified in the associated data-set descriptor or default filename block contains an explicit file 
version number (including 0 and —1). 


DELET$ fdb,err 


Parameters 


fdb 
Specifies a symbolic value of the address of the associated FDB. 


err 
Specifies the symbolic address of an optional error-handling routine, which you coded. 


Note 


If the DELET$ macro is issued for use with a file containing sensitive information, it is 
recommended that you zero the file before closing it. (Although DELET$ logically removes a 
file, the information physically remains on the volume until written over with another file, and 
could be analyzed by unauthorized user tasks.) 
Examples 

DELETS RO 

DELET$ #OUTFDB, ERRLOC 

DELET$ RO,ERRLOC 


Shows how the DELET$ macro may be used in a program. 
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File Control Routines 


This chapter describes a set of file control routines that you can invoke in MACRO-11 programs to 
perform the following functions: 


¢ Read or write default directory string descriptors in program section $$FSR2. 

¢ Read or write the default User Identification Code (UIC) word in program section $$FSR2. 
¢ Read or write the default file protection word in program section $$FSR2. 

¢ Read or write the file owner word in program section $$FSR2. 


¢ Convert a directory string from American Standard Code for Information Interchange (ASCII) 
to binary or from binary to ASCII. 


¢ Fill in all or part of a filename block from a data-set descriptor or default filename block. 
e Find, insert, or delete a directory entry. 

e Set a pointer to a byte within a virtual block or to a record within a file. 

¢ Mark a place in a file for a subsequent OPEN$x operation. 

e Issue an I/O command and wait for its completion. 

¢ Rename a file. 

e Extend a file. 

¢ Truncate a file. 

¢ Mark a temporary file for deletion. 

¢ Delete a file by filename block. 


¢ Perform device-specific control functions. 


Calling File Control Routines 


The CALL macro invokes file control routines (JSR PC, dst). The Task Builder (TKB) includes 
these routines from the system object library ({1,1JSYSLIB.OLB) at task-build time and 
incorporates them into your task. Your task calls the following file control routines: 


CALL .RDFDR 

CALL .EXTND 
Before your task issues the CALL macro, certain file control routines require that specific registers 
be preset with requisite information. The descriptions of the respective routines identify these 


requirements. Upon return to your task, all task registers are preserved except for those that have 
been explicitly specified as changed. 


If a file control routine detects an error, it sets the Carry bit indication to FDB offset location 
F.ERR. However, certain file control routines do not return error indications even if one is present. 
The following file control routines are listed according to whether they return error indications. 
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Normal Error Return 


(Carry Bit and F.ERR) No Error Return — 
ASCPP -RDFDR 
-PARSE .WDFDR 
-PRSDV .RDFUI 
.PRSDI .WDFUI 
.PRSDV .RDFFP 
“ASLUN .WDFFP 
-FIND — -RFOWN 
-ENTER .WFOWN 
-REMOV .PPASC 
.GTDIR .MARK 
.GTDID 

.POINT 

.POSRC 

.POSIT 

.XQIO 

.RENAM 

-EXTND 

sTRNCL 

.MRKDL 

.DLFNB 

.CTRL 


Appendix K lists the error codes that the routines return in a File Descriptor Block (FDB) offset 
location F.ERR. 


Default Directory String Routines 
The .RDFDR and .WDFDR routines read and write directory string descriptors. 


.RDFDR—Read $$FSR2 Default Directory String Descriptor 


Your task calls the .RDFDR routine to read default directory string descriptor words previously 
written by the .WDFDR routine into program section $$FSR2 of the file storage region (FSR). 
These descriptor words define the address and the length of an ASCII string that contains the 
default directory string. This directory string is the default directory that File Control Services 
(FCS) uses when a directory is not specified in a data-set descriptor. 


If you have not established default directory string descriptor words in program section $$FSR2 by 
using the .WDFDR routine described in the following text, the descriptor words in program section 
$$FSR2 are null. FCS uses a default directory (when one is not specified in a data-set descriptor) 
corresponding to the UIC under which the task is running. 
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When called, the .RDFDR routine returns values in the following registers: 


R1 Contains the size (in bytes) of the default directory string in program section $$FSR2. 


R2 Contains the address of the default directory string in program section $$FSR2. If no default directory string 
descriptor words have been written by .WDFDR, R2 equals 0. 


.WDFDR—Write New $$FSR2 Default Directory String Descriptor 


Your task calls the .WDFDR routine to create default directory string descriptor words in program 
section $$FSR2. For example, if your program is to operate on files in the directory [220,220], 
regardless of the UIC under which the program runs, you can establish default directory string 
descriptor cells in program section $$FSR2 to point to this alternate directory string [220,220] 
created elsewhere in the program. To do this, first create the desired directory string through an 
.ASCII directive. Then, by calling the .WDFDR routine, you can initialize the default directory 
string descriptor cells in program section $$FSR2 to point to the new directory string. 


Assume that the task is currently running under default UIC [200,200]. You define a new directory 
string by issuing the following MACRO-11 directive: 


NEWDDS : -ASCII /[220,220]/ 


By calling the .WDFDR routine, you initialize string descriptor cells in program section $$FSR2 to 
point to the new directory string. 


You must preset the following registers before your task calls the .WDFDR routine: 
R1 Must contain the size (in bytes) of the new directory string. 

R2 Must contain the address of the new directory string. 

Note 


Establishing default directory string descriptor words in program section $$FSR2 does not change 
the default UIC in program section $$FSR2 or the task’s privileges. 


Default UIC Routines 


The .RDFUI and .WDFUI routines read and write the default UIC maintained in program section 
$$FSR2 of the FSR. Unlike the default directory string descriptor that describes an ASCII string, 
the default UIC is maintained as a binary value with the format shown in Figure 4—1. 


Figure 4-1 Default UIC Format 
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The default UIC in program section $$FSR2 provides directory identification information for a file 
being accessed. FCS uses the default UIC only when all other sources of such information have 
failed to specify a directory (refer to Section 4.7.1.2). FCS never uses the default UIC to establish 
file ownership or file access privileges. 


Unless you change the default UIC through the .WDFUI routine described in the following text, 
the default UIC in program section $$FSR2 always corresponds to the UIC under which the task 
is running. 


4.3.1 .RDFUI—Read Default UIC 
Your task calls the .RDFUI routine to return the default UIC as follows: 
R1 Contains the binary-encoded default UIC maintained in program section $$FSR2. 


4.3.2 .WDFUI—Write Default UIC 
Your task calls the .WDFUI routine to create a new default UIC in program section $$FSR2. 
You must preset the following register before calling the WDFUI routine: 


R1 Must contain the binary representation of a UIC. 


Note 


The .WDFUI routine overrides any default UIC descriptor in program section $$FSR2 that was 
previously created by the .WDFDR routine. 


4.4 Default File Protection Word Routines 


The .RDFFP and .WDFFP routines described in the following text read and write the default file 
protection word in a location in program section $$FSR2 of the FSR. FCS uses this word only when 
a file is created (for example, by the OPEN$W macro call) to establish the default file protection 
values for the new file. Unless altered, this value constitutes the default file protection word for 
that file. If the value is —1, it indicates that the volume default file protection value is to be used 
for the new file. 


The default file protection word has four file protection categories: world, group, owner, and 
system. The format of the default file protection is shown in Figure 4—2. 


Figure 4-2 File Protection Word Format 
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Figure 4-3 File Protection Access Bits 
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‘Each of these four file protection categories has four bits; each bit represents the kind of access 


allowed to a file, as shown in Figure 4—3. 


A bit value of 0 indicates that the corresponding file access is to be allowed; a bit value of 1 
indicates that the access is to be denied. 


.RDFFP-—Read $$FSR2 Default File Protection Word 


You call the .RDFFP routine to read the default file protection word in program section $$FSR2 of 
the FSR. No registers need be set before calling this routine. 


When called, the .RDFFP routine returns the following information: 


R1 Contains the default file protection worcl from program section $$FSR2. 


.WDFFP-—Write New $$FSR2 Default File Protection Word 


You use the .WDFFP routine to write a new default file protection word into program section 
$$FSR2. 


You must preset the following register before calling the .WDFFP routine: 


R1 Must contain the new default file protection word to be written into program section $$FSR2. If this register 
is set to -1, the default file protection values established through the appropriate operating system command 
will be used in creating all subsequent new files. 


File Owner Word Routines 


The file owner word, like the default file protection word, is a location in program section $$FSR2 
of the FSR. Its contents are specified by the current program through the .WFOWN routine. If not 
so specified, the file owner word contains 0. 


For nonprivileged users, the owner of a new file corresponds to the default UIC specification, as 
follows: 


¢ If the volume on which the new file is created is private (allocated), the owner UIC is the same 
as the UIC of the task creating the file. 


¢ Ifthe volume on which the new file is created is a system volume, the owner UIC is the same 
as the task’s login UIC. 


For privileged users, the owner UIC is always the same as the UIC of the task creating the file. 


Note that for files created by privileged or nonprivileged tasks that are started by a time-scheduled 
request, the owner UIC is set to the UIC specified at task-build time. 
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A specific UIC value can be stored in the file owner word by the .WFOWN routine (see Section 
4.5.2). All new files then created and closed by your task will contain the specified UIC value. 


The format of the file owner word is shown in Figure 4-4. 


Figure 4-4 File Owner Word Format 


Bit 15 8 7 0 


The routines for reading and writing the file owner word are described in Sections 4.5.1. and 4.5.2. 


NOTE: The UIC and the file protection word for the file (see Section 4.4) must not be set 
such that the UIC under which the task is running does not have access to the file. This 
condition results in a privilege violation. 


When a file is created, the owner UIC is always set to either the UIC of the task creating the file 
or the task’s login UIC, as previously described. However, when closing the file, you can change 
the owner UIC by using the WFOWN routine. If the file is not closed properly, the owner UIC will 
not change. 


.RFOWN—Read $$FSR2 File Owner Word 


You use the .RFOWN routine to read the contents of the file owner word in program section 
$$F'SR2. No registers need be preset before calling this routine. 


When called, the RFOWN routine returns the following information: 


R1 Contains the file owner word (UIC). If the current program has not previously established the contents of 
the file owner word through the .WFOWN routine, R1 contains 0. 


.WFOWN—Write New $$FSR2 File Owner Word 


You use the .WFOWN routine to initialize the file owner word in program section $$FSR2. 
You must preset the following register before calling this routine: 


R1 Must contain a file owner word to be written into $$FSR2. 


ASCIl/Binary UIC Conversion Routines 


Your task calls the ASCPP and .PPASC routines to convert a directory string from ASCII to binary 
or from binary to ASCII. 
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.ASCPP-—Convert ASCII Directory String to Equivalent Binary UIC 


Your task calls the ASCPP routine to convert an ASCII directory string to its corresponding binary 
VIC. 


You must preset the following registers before calling this routine: 
R2 Must contain the address of the directory string descriptor in your program (see Chapter 2) for the string to 
be converted. 


R3 Must contain the address of a word location in your program to which the binary UIC is to be returned. 
The member number is stored in the low-order byte of the word, and the group number is stored in the 
high-order byte. 


.PPASC—-Convert UIC to ASCII Directory String 


Your task calls the .PPASC routine to convert a binary UIC to its corresponding ASCII directory 
string. 


You must preset the following registers before calling this routine: 
R2 Must contain the address of a storage area within your program into which you place the ASCII string. The 
resultant string can be up to 9 bytes in length, for example, [200,200]. 


R3 Must contain the binary UIC value to be converted. The low-order byte of the register contains the member 
number, and the high-order byte of the register contains the group number. 
R4 Must contain a control code. Bits 0 and 1 of this register indicate the following: 
Bit 0 Is set to 0 to suppress leading zeros (for example, 001 is returned as 1). Bit 0 is set to 1 to 
indicate that leading zeros are not to be suppressed. 


Bit 1 Is set to 0 to place separators (square brackets and commas) in the directory ould (for example, 
[10,20]). Bit 1 is set to 1 to suppress separators (for example, 1020). 


The .PPASC routine adds to the contents of R2, allowing R2 to point to the byte immediately 
following the last byte in the converted directory string. 


Filename Block Routines 


FCS provides the PARSE, .PRSDV, .PRSDI, .PRSFN, and .ASLUN routines, which perform 
functions related to a specified filename block. These routines are described in the following 
sections. 


.PARSE—Fill in All File Name Information 


When called, the PARSE routine first zeros the filename block pointed to by R1 and then stores 
the following information in the filename block: 


¢ The ASCII device name (N.DVNM) 

¢ The binary unit number (N.UNIT) 

¢ The directory ID (N.DID) 

¢ The Radix-50 file name (N.FNAM) 

¢ The Radix-50 file type or extension (N.FTYP) 
¢ The binary file version number (N.FVER) 
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For American National Standards Institute (ANSI) magnetic tape file names, the following 
information is stored in the filename block: 


¢ The ASCII device name (N.DVNM) 

e The binary unit number (N.UNIT) 

e The file name as 17 ASCII bytes (N.ANM1 and N.ANM2) 
¢ The binary file version number (N.FVER) 


In addition, the .PARSE routine calls the .ASLUN routine to assign the logical unit number (LUN) 
associated with the FDB to the device and unit currently specified in the filename block. 


Both formats for filename blocks are shown in detail in Appendix B. 


Before the .PARSE routine can be called, the FINIT$ macro (see Chapter 2) must be invoked 
explicitly in your program, or it must be invoked implicitly through a prior OPEN$x macro call. 
Note, however, that your task can issue the FINIT$ call only once in the initialization section 
of the program; that is, the FINIT$ operation must be performed only once per task execution. 
Furthermore, FORTRAN programs issue a FINIT$ call at the beginning of task execution; 
therefore, MACRO-11 routines used with the FORTRAN object time system must not issue a 
FINIT$ macro. 


You must preset the following registers before calling the PARSE routine: 


RO Must contain the address of the desired FDB. 


R1 Must contain the address of the filename block to be filled in. This filename block is usually, but not 
necessarily, the filename block within the FDB specified in RO (that is, RO + F.FNB). 


R2 Must contain the address of the desired data-set descriptor if PARSE is to access a data-set descriptor 
in filling in the specified filename block. This structure is usually, but not necessarily, the same as that 
associated with the FDB specified in RO (that is, the data-set descriptor pointed to by the address value in 
F.DSPT). 

If R2 contains 0, a data-set descriptor has not been defined; therefore, the data-set descriptor logic of the 
-PARSE routine is bypassed. 

R3 Must contain the address of the desired default filename block for the .PARSE routine to access a default 
filename block in filling in the specified filename block. This default filename block is usually, but not 
necessarily, the same as the one associated with the FDB specified in RO (that is, the default filename 
block pointed to by the address value in F.DFNB). 


If R3 contains 0, a default filename block has not been defined; therefore, the default filename block logic 
of the .PARSE routine is bypassed. 


Thus, RO and R1 each must contain the address of the appropriate data structure, while either 
R2 or R3 must contain the address of the desired filename information. Both R2 and R3, however, 
may contain address values if the referenced structures both contain information required in filling 
in the specified filename block. 


The .PARSE routine fills in the specified filename block in the order described in the following 
sections. 


4.7.1.1 Device and Unit Information 
The .PARSE routine first tries to fill in the filename block with device (N.DVNM) and unit 
(N.UNIT) information. The following operations are performed until the required information 
is obtained from the specified data structures: 


1 If the address of a data-set descriptor is specified in R2 and the data-set descriptor contains 
a device string, the .PARSE routine moves the device and unit information from the data-set 
descriptor into the specified filename block. 
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2 If step 1 fails, and if the address of a default filename block is specified in R3, and the default 
filename block contains a nonzero value in the device name field, the PARSE routine moves 
the device and unit information from the device name field into the specified filename block. 


3 If step 2 fails, the PARSE routine uses the device and unit currently assigned to the LUN in 
offset location F.LUN of the specified File Descriptor Block (FDB) to fill in the filename block. 


This feature allows a program to use preassigned logical units that are assigned through 
either the device assignment (ASG) option of the Task Builder (TKB) or one of the following 
commands: ASSIGN in the DIGITAL Command Language (DCL) or ASN in the Monitor 
Console Routine (MCR). In this case, you simply avoid specifying the device string in the 
data-set descriptor and the device name in the default filename block. 


4 Ifthe LUN in F.LUN is currently unassigned, the .PARSE routine assigns this number to the 
system device (SY0). 


The .PARSE routine first determines the device and unit, assigns the LUN, and then invokes the 
GLUN$ directive to obtain necessary device information. The required information obtained by 
GLUNS$ is placed by the .PARSE routine into the following offsets in the filename block pointed to 
by R1: 


N.DVNM Device Name Field. This field contains the redirected device name. 
N.UNIT Unit Number Field. This field contains the redirected unit number. 


Additionally, the .PARSE routine places the information returned by GLUN$ into the following 
offsets in the FDB, which RO points to: 


F.RCTL Device Characteristics Byte. This cell contains device-dependent information from the first byte 
of the third word returned by the GLUN$ directive. The bit definitions pertaining to the device 
characteristics byte are described in detail in Appendix A. If desired, you can examine this cell in the 
FDB to determine the characteristics of the device associated with the assigned LUN. 


F.VBSZ Device Buffer Size Word. This location contains the information from the sixth word returned by 
the GLUN$ directive. The value in this cell defines the device buffer size (in bytes) of the device 
associated with the assigned LUN. 


The GLUN$ directive is described in detail in the JAS Executive Reference Guide. 


4.7.1.2 Directory Identification Information 
The N.DID field in the filename block contains the following information: 


Word Meaning 
File ID 


File sequence number 
Reserved 


The .PARSE routine moves these three words from the Master File Directory (MFD) to the N.DID 
field in the filename block. The file ID is the header number of the header (in the index file) for 
a User File Directory (UFD). The .FIND routine uses the file ID to locate and search a UFD and 
to fill in the N.FID field in the filename block. The N.FID has the same format as the N.DID field 
except that it identifies the header number of the header for a user data file. The file sequence 
number is incremented each time a file header is reused for a new file. 
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Following the operations described in the preceding section, PARSE attempts to fill in the filename 
block with directory identification (N.DID) information. The methods for obtaining this information 
are as follows: 


1 If your task specifies the address of a data-set descriptor in R2 and the data-set descriptor 
contains a directory string, File Control Services (FCS) uses that directory string to find the 
associated UFD in the MFD. The resulting file ID is then moved into the directory-ID field of 
the specified filename block. 


2 If step 1 fails, and your task specifies the address of a default filename block in R3, and the 
default filename block contains a nonzero directory ID, the contents of the default filename 
block are moved into the specified filename block. 


Because none of the parameters of the NNBLK$ macro call (see Chapter 2) initialize the 
three words starting at offset location N.DID in the default filename block, your task must 
initialize these cells manually. Or your task can call the .GTDIR routine (see Section 4.9.1) or 
the .GTDID routine (see Section 4.9.2). Note that these routines can also initialize a specified 
filename block directly with required directory information. 


3 If neither step 1 nor step 2 yields the required directory string, the PARSE routine examines 
the default directory string words in program section $$FSR2. If your program has previously 
initialized these words through use of the .WDFDR routine, FCS uses the string described as 
the default directory. 


4 If steps 1 to 3 fail to produce directory information, FCS uses the binary value stored in the 
default UIC word in program section $$FSR2 as the directory identifier. Unless changed by 
you through the .WDFUI routine, this word contains the UIC under which the task is running. 


NOTE: The .PARSE routine does not accept UICs that contain wildcards. Additionally, 
the .PARSE routine does not set filename block status word (N.STAT) bits NB.SD1 or 
NB.SD2 (group and owner wildcard specifications, respectively). 


4.7.1.3 File Name, File Type, and File Version Information 
After completing the operations described in the preceding section, the .PARSE routine attempts to 
obtain file name information (N.FNAM, N.FTYP, and N.FVER), as follows: 


1 If your task specifies the address of a data-set descriptor in R2 and this structure contains a 
filename string, the file name information therein is moved into the specified filename block. 


2 If your task specifies the address of a default filename block in R3, and one or more of the file 
name, file type, and file version number fields of the data-set descriptor that you specified in 
R2 are null, the corresponding fields of the default filename block fill in the specified filename 
block. 


3 If neither step 1 nor step 2 yields the requisite file name information, any specific fields not 
available from either source remain null. 


NOTE: If a period (.) appears in the filename string without an accompanying file 
type designation (for example, TEST. or TEST.;3), FCS interprets the file type as being 
explicitly null. In this case, the default file type is not used. 


Similarly, if a semicolon (;) appears in the filename string without an accompanying file 
version number (for example, TEST.DAT;), FCS also interprets the file version number 
as being null; again, the default file version number is not used. This information 
concerning semicolons in filename strings does not apply to the 17-byte ASCII filename 
strings supported for ANSI magnetic tape. 
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4.7.1.4 Using the FDB Extension for Logical Names 
FCS uses the FDB extension to obtain the correct directory string. The extension has the following 
format: 


-.BYTE Extension length 

BYTE Unused 

BYTE Length of the directory string buffer 

BYTE Length of the directory string (filled in by .PRSDI) 
WORD _ Address of the directory string buffer 


The FDB extension block and the directory string buffer are allocated in your task’s address space. 
You fill in the address, the length of the buffer, and the length of the extension into the appropriate 
locations in the FDB extension block. You then place the address of the extension block in the 
offset F.EXT in the FDB. When the directory parsing code detects that F.EXT has a value, it uses 
the value as an address and moves the directory string into the buffer. It also puts the length 

of the actual directory string into the appropriate byte of the extension. This directory string is 
always filled in, unless FCS obtains the directory from the default name block, because the default 
name block does not contain the directory string. If FCS obtains the directory from the default 
name block, FCS sets the directory length to zero. 


471.5 Other Filename Block Information 
After performing all the previously described operations, the .PARSE routine also fills in the status 
word (offset location N.STAT) of the N.STAT\ master) filename block specified in R1. 


The bit definitions for this word are presented in Appendix B. Note that in Appendix B, Table B-2 
the directory, device, file name, file type, or file version number specification pertains to ASCII data 
supplied through the data-set descriptor pointed to by R2. 


In addition, the .PARSE routine zeros offset location N.NEXT in the filename block pointed to by 
Rl. This action has implications for wildcard operations, as described in Section 4.8.1. 


4.7.1.6 -EXPLG Module (Expand Logical) 
The .EXPLG module expands a logical name and returns a pointer to the task that points to the 
expanded string. The module has the following inputs and outputs: 


Inputs R2-—Pointer to the data-set descriptor of the string to be expanded. 
Outputs R2-—Pointer to the data-set descriptor of the expanded string. All other registers are preserved. 


This routine expands the string into the same buffer that the .PARSE routine and CSI$4 use for 
input files; therefore, caution is advised if you use this method. In addition, the call only accepts 
logical names that expand into a correct FCS file specification. The inclusion of a node specifier or 
other non-FCS characters results in an error being returned. 


-PRSDV_—-Fill in Device and Unit Information Only 


The .PRSDV routine is identical to the .PARSE routine, except that it performs only those 
operations associated with requisite device and unit information (see Section 4.7.1.1). The .PRSDV 
routine zeros the filename block pointed to by R1, calls the PARSE routine to operate on the device 
and unit fields in the specified data-set descriptor or default filename block, and assigns the LUN 
contained in offset location F.LUN of the specified FDB. 
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After the logical device translation is performed, .PRSDV fills the filename block with the required 
device and unit information. If the device is LB, the actual physical device name and unit are 
placed in the filename block. If the logical device expands to contain anything other than a device 
specification, for example, a directory or a filename, the remainder is ignored. Setting the FL.AEX 
bit (see Chapter 6) disables logical expansion for the device and unit information. 


.-PRSDI—Fill in Directory Identification Information Only 


The .PRSDI routine is identical to the .PARSE routine, except that it performs only those 
operations associated with requisite directory identification information (see Section 4.7.1.2). The 
.PRSDI routine performs a .PARSE operation on the directory identification information (N.DID) 
field in the specified data-set descriptor or default filename block. The .PRSDI routine does not 
perform any logical name expansion. 


-PRSFN—Fill in File Name, File Type, and File Version Only 


The .PRSFN routine is identical to the PARSE routine, except that it performs only those 
operations associated with requisite file name, file type, and file version information (see Section 
4.7.2.3). This routine performs a .PARSE operation on the file name, file type, and file version 
information fields (N.FNAM, N.FTYP, N.FVER) in the specified data-set descriptor or default 
filename block. The .PRSFN routine does not perform any logical name expansion. 


ASLUN—Assign LUN 


The .ASLUN routine assigns a logical unit number (LUN) to a specified device and unit and 
returns the device information to a specified FDB and filename block. 


You must preset the following registers before calling this routine: 


RO Must contain the address of the desired FDB. 
R1 Must contain the address of the filename block where the desired device and unit information are located. 
This filename block is usually, but not necessarily, within the FDB specified by the address in RO. 


If the device name field (offset location N.DVNM) of the filename block pointed to by R1 contains 
a nonzero value, the specified device and unit are assigned to the LUN contained in offset location 
F.LUN in the FDB pointed to by RO. 


If offset location N.DVNM in the filename block contains 0, then the device and unit currently 
assigned to the specified LUN are returned to the appropriate fields of the filename block. 


Finally, if the specified LUN is not assigned to a specific device, the ASLUN routine assigns it to 
the system device (SY0) by default. 


The information returned to the specified filename block and the specified FDB is identical to that 
returned by the device and unit logic of the PARSE routine (see Section 4.7.1.1). 


Directory Entry Routines 


The .FIND, ENTER, and .REMOV routines find, insert, and delete directory entries. The term 
“directory entry” refers to entries in both the MFD and the UFD. 
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.FIND—Locate Directory Entry 


You call the .FIND routine to locate a directory entry by file name and to fill in the file 
identification field (N.FID) of a specified filename block. 


You must preset the following registers before calling this routine: 


RO Must contain the address of the desired FDB. 


R1 Must contain the address of a filename block. This filename block is usually, but not necessarily, within the 
FDB specified by the address in RO. 


When invoked, the .FIND routine searches the directory file specified by the directory-ID field of 
the filename block. This file is searched for an entry that matches the specified file name, file type, 
and file version number. Two special file versions are defined as follows: 


¢ Version 0 is matched by the latest (largest) version number encountered in the directory file. 


¢ Version —1 is matched by the oldest (smallest) version number encountered in the directory file. 


If either of these special versions is specified in the filename block, the matching version number 
is returned to the filename block. In this way, the actual version number is made available to the 
program. 


Certain wildcard operations require the use of the .FIND routine. Three bits in the filename block 
status word (see N.STAT in Appendix B, Table B-2) indicate whether a wildcard (*) was specified 
for a file name, a file type, or a file version number field. If the wildcard bit in N.STAT is set for 

a given field, any directory entry matches that corresponding field. Thus, if the file name and file 
version number fields contain wildcard specifications (* ), and the file type field is specified as .OBJ 
(that is, *.OBJ;*), the first directory entry encountered that contains .OBJ in the file type field 
matches. 


When a wildcard match is found, the complete file name, file type, and file version number fields of 
the matching entry are returned to the filename block, along with the file-ID field (N.FID). Thus, 
the program can determine the actual name of the file just found. Offset location N.NEXT in the 
filename block is also set to indicate where that directory entry was found in the directory file. 
FCS uses this information in subsequent, .FIND operations to locate the next matching entry in the 
directory file. 


For example, the .FIND routine often opens a series of files when wildcard specifications are used. 
The following operations are typical: 


1. Call the .PARSE routine. This routine zeros offset location N.NEXT in the filename block in 
preparation for the iterative .FIND operations described in step 3. 


2 Check for wildcard bits set by the .PARSE routine in the filename block status word (see 
N.STAT in Appendix B, Table B-2). An instruction sequence such as that shown in the 
following text tests for the setting of wildcard bits in N.STAT: 


BIT #NB.SVR!NB.STP!NB.SNM,N.STAT(R1) 
BEQ NOWILD ;BRANCH IF NOT SET. 


3 If wildcard specifications are present in the filename block status word, repeat the following 
sequence until all the desired wildcard files have been processed: 


CALL -FIND 

BCS DONE 7;ERROR CODE IE.NSF INDICATES 
7;NORMAL TERMINATION. 

OPENS RO 
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Wildcard .FIND operations update offset location N.NEXT in the filename block. In essence, 
the contents of this cell provide the necessary information for continuing the directory file 
search for a matching entry. 


4 Perform the desired operations on the file. 


NOTE: This procedure applies only to the following types of wildcard file specifications: 


TEST .DAT; * 
TEST.*;* 

* DAT; * 
TEST.*;5 

* DAT; 3 


This procedure does not work for the following types of wildcard file specifications: 


* DAT 
TEST.* 


In summary, if a wildcard file specification is present in either the file name field or the file type 
field, the file version number field must also contain either an explicit wildcard specification (*) or 
a specific file version number. In the latter case, however, the version number cannot be 0, for the 
latest version of the file, or —1, for the oldest version of the file. 


When your task sets NB.ANS, the .FIND operation compares the file name against the full 
17-character ANSI filename string that is stored in the filename block (see Appendix B). When 
NB.ANS is clear, the file name is converted to Radix-50 format, as described in Appendix C. 


ANSI magnetic tape file names in the following formats can be converted to Radix-50 format: 
¢ Up to nine Radix-50 characters followed by spaces 


¢ Up to nine Radix-50 characters followed by a period, followed by spaces, or followed by a 
3-character file type 


Note that unless NB.ANS is set before the call to .FIND, some file names may be incorrectly 
matched. For example, the names “ABC” and “ABC.” are considered the same when compared with 
the name ABC in Radix-50 format. 


When a wildcard operation is performed, the name returned in the filename block is normally 
converted to Radix-50 format. However, if NB.ANS is set, the ANSI filename string is returned 
as up-to-17 ASCII bytes. The first 12 bytes are returned at offset N.ANM1 in the ANSI filename 
block. The remainder are returned at offset N.ANM2. 


It is incorrect to set NB.ANS before a wildcard .FIND operation unless both file name and file type 
are wild, or neither file name nor file type are wild. — 


To delete a file whose file descriptor entry in the FDB contains wildcards, you must save the values 
in the fields N.STAT and N.NEXT in the FDB, and then zero these fields in the FDB. A DELETE 
call then uses the information returned from the last .FIND to delete the file. Once the file is 
deleted, the saved values of N.STAT and N.NEXT must be restored in the FDB. 


-ENTER—Insert Directory Entry 


You use the .ENTER routine to insert an entry by file name into a directory. 
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You must preset the following registers before calling this routine: 


RO Must contain the address of the desired FDB. 
R1 Must contain the address of a filename block. This filename block is usually, but not necessarily, the 
filename block within the FDB specified in Ro. 


If the file version number field of the filename block contains 0, indicating a default version 
number, the ENTER routine scans the entire directory file to determine the current highest 
version number for the file. If a version number for the file is found, this entry is incremented to 
the next higher version number; otherwise, it is set to 1. The resulting version number is returned 
to the filename block, making this number known to the program. 


Note 


Wildcard specifications cannot be used in connection with .ENTER operations. 


-REMOV-—Delete Directory Entry 


You use the .REMOV routine to delete an entry from a directory by file name. This routine deletes 
only a specified directory entry; it does not delete the associated file. 


You must preset the following registers before calling this routine: 


RO Must contain the address of the desired FDB. 


R1 Must contain the address of a filename block. This filename block is usually, but not necessarily, the 
filename block within the FDB specified in RO. 


Wildcard specifications operate in the same manner as those defined for the .FIND routine 
described in Section 4.8.1. The file version number for .REMOV operations must be an explicit 
number (including 0 and —1) or a wildcard. Each .REMOV operation deletes the next directory 
entry that has the specified file name, file type, and file version number. 


Filename Block Routines 


The .GTDIR and .GTDID routines insert directory information in a specified filename block. 
Sections 4.9.1 and 4.9.2 describe the use and operation of these routines. 


.GTDIR—Insert Directory Information in Filename Block 


You call the .GTDIR routine to insert directory information from a directory string descriptor into 
a specified filename block. 


You must preset the following registers before calling this routine: 


RO Must contain the address of the desired FDB. 


R1 Must contain the address of the filename block in which the directory information is to be placed. This 
filename block is usually, but not necessarily, within the FDB specified by the address in RO. 

R2 Must contain the address of the 2-word directory string descriptor in your program. This string descriptor 
defines the size and the address of the desired directory string. 


This routine performs a .FIND operation for the specified UFD in the MFD and returns the 
resulting directory ID to the three words of the specified filename block, starting at offset location 
N.DID. The .GTDIR routine preserves the information in offset locations N.IFNAM, N.FYTP, 
N.FVER, N.DVNM, and N.UNIT of the filename block, but the routine clears the rest of the 
filename block. 
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You can also use the .GTDIR routine with the NMBLK$ macro call (see Chapter 2) to insert 
directory information into a specified default filename block. 


.GTDID—Insert Default Directory Information in Filename Block 


The .GTDID routine provides an alternative means for inserting directory information into a 
specified filename block. Instead of allowing the specification of the directory string, as does the 
.GTDIR routine, this routine uses the binary value found in the default UIC word maintained in 
program section $$FSR2 as the desired UFD. 


You must preset the following registers before calling the .GTDID routine: 


RO Must contain the address of the desired FDB. 


R1 Must contain the address of a filename block in which the directory information is to be placed. This 
filename block is usually, but not necessarily, within the FDB specified by the address in RO. 


When called, the .GTDID routine takes the default UIC from its 1-word location in program 
section $$FSR2 and performs a .FIND operation for the associated UFD in the MFD. The resulting 
directory ID is returned to the three words of the specified filename block, starting at offset location 
N.DID. As does the .GTDIR routine, .GTDID preserves offset locations N.FNAM, N.FTYP, N.FVER, 
N.DVNM, and N.UNIT in the filename block, but .GTDID clears the rest of the filename block. 


The .GTDID routine uses considerably less code than the .GTDIR routine. Its input is the binary 
representation of a UIC rather than an ASCII string descriptor. Therefore, it does not invoke the 
-PARSE logic; furthermore, .GTDID is specifically for use in programs that open files by using the 
OFNB$ macro call (see Chapter 3). Such a program does not invoke the .PARSE logic because all 
necessary file name information is provided to the program in filename block format. 


Like the .GTDIR routine described in Section 4.9.1, the GGTDID routine can be used with the 
NMBLK$ macro call (see Chapter 2) to insert directory information (N.DID) into a specified default 
filename block. You also have the option to initialize offset location N.DID manually with the 
required directory information. 


The .GTDID routine returns file-ID 177777,177777,0 for nondirectory devices such as terminals. 


File Pointer Routines 


The .POINT, .POSRC, .MARK, and .POSIT routines point to a byte or a record within a specified 
file. Sections 4.10.1 to 4.10.4 briefly describe the use of these routines and their operation. 


-POINT—Position File to Specified Byte 


You call the .POINT routine to position a file pointer to a specified byte in a specified virtual block. 
If locate mode is in effect for record I/O operations, the .POINT routine also updates the value 

in offset location F NRBD+2 in the associated FDB in preparation for a PUT$ operation in locate 
mode. 


You must preset the following registers before calling this routine: 


RO Must contain the address of the desired FDB. 
R1 Must contain the high-order bits of the virtual block number. 
R2 Must contain the low-order bits of the virtual block number. 
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R3 Must contain the desired byte number within the specified virtual block. 


For a description of virtual block numbers and how these 2-word values are formed, refer to 
Chapter 2. 


NOTE: Use of the .POINT routine is restricted to files accessed with GET$ or PUT$ 
macros. For files accessed with READ$ or WRITE$ macros, use the FDBK$R macro to 
initialize the block access section of the FDB. 


The .POINT routine is used often with the .MARK routine and achieves a limited degree of random 
access with variable-length records. The .MARK routine saves the positional information of a 

file, permitting you to temporarily close that file and to reopen it later at the same position; this 
procedure is outlined in the following steps: 


1 Call the .MARK routine to save the current positional context of the file. 
Close the file. 

Reopen the file when desired. 

Load the information returned by the .MARK routine into R1, R2, and R3. 


Call the .POINT routine. The .POINT routine may be called to rewind a file on disk or ANSI 
magnetic tape to its start. For this case, Rl and R3 must be set to 0, and R2 must be set to 1. 
The .POINT routine may also be called to rewind a file that is open on a terminal. Doing so 
clears the terminal end-of-file condition. 


a & WwW ND 


6 Resume processing of the file. 


.POSRC-—Position File to Specified Record 


The .POSRC routine sets up the position information for a file to a specified fixed-length record 
within a file. If locate mode is in effect for record I/O operations, the .POSRC routine also updates 
the value in offset location F NRBD+2 in the associated FDB in preparation for a PUT$ operation 
in locate mode. 


Before calling this routine, you must set offset locations F. RCNM+2 and F.RCNM in the FDB to the 
desired record number and ensure that the correct record size is reflected in offset location F.RSIZ 
of the FDB. 


The following register must be preset before calling the .POSRC routine: 
RO Must contain the address of the associated FDB. 


You use the .POSRC routine when performing random access PUT$ operations in locate mode. 
Normally, PUT$ operations in locate mode are sequential; however, when you use random access 
mode, you must follow the next procedure to ensure that the record is built at the desired location: 


1 Set offset locations FRCNM+2 and F.RCNM in the associated File Descriptor Block (FDB) to 
the desired record number. 


Call the .POSRC routine. 


Build the new record at the address returned (by the .POSRC call) in offset location F.NRBD+2 
of the associated FDB. 


4 Perform the PUT$ operation. 
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4.10.3 .MARK—Save Position Information Context of File 


The .MARK routine allows you to save the current position information of a file for later use; you 
can save the current position information of a file, close that file, and later reopen the file to the 
same position. The .MARK routine also allows you to alter records within a file; you can save the 
file position, retrieve information elsewhere in that file, and return to the saved position of the 
file to alter the desired record. This sequence may be repeated to update any number of desired 
records in the file. 

You must preset the following register before calling the MARK routine: 

RO Must contain the address of the associated FDB before calling this routine. 

When called, the MARK routine returns information to the following registers: 

R1 Contains the high-order bits of the virtual block number. 

R2 Contains the low-order bits of the virtual block number. 

R3 Contains the number of the next byte within the virtual block. 


R3 points to the next byte in the block. For example, if four GET$ operations are performed, 
followed by a call to the .MARK routine, R3 points to the first byte in the fifth record in the file. 


4.10.4 .POSIT—Return Specified Record Position Information 


The .POSIT routine calculates the virtual block number and the byte number locating the 
beginning of a specified record. 


The following register must be preset before calling this routine: 
RO Must contain the address of the associated FDB. 


In addition, offset locations FRCNM and F.RCNM+2 in the associated FDB must contain the 
desired record number. 


Unlike the .POSRC routine, which sets up the position information of the file to the specified 
record, .POSIT calculates the positional information of a specified record so that a .POINT 
operation can be performed later to position to the desired record. 


The .POSIT routine returns register values identical to those described previously for the MARK 
routine. 


4.11 .XQIO—Queue I/O Function Routine 


The Queue I/O Function Routine (.XQIO) executes a specified QIO$ function and waits for its 
completion. 


You must preset the following registers before calling this routine: 


RO Must contain the address of the desired FDB. 


R1 Must contain the desired QlIO$ macro function code. Refer to the [AS Device Handlers Manual for the 
desired QiIO$ macro function codes. 


R2 Must contain the number of optional parameters, if any, to be included in the QIO$ directive. 


R3 Must contain the beginning address of the list of optional QIO$ directive parameters, if R2 contains a 
nonzero value. Refer to the /AS Device Handlers Reference Manual for the parameter list. 
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-RENAM—Rename File Routine 


The .RENAM routine is called to change the name of a file in its associated directory. To rename 
a file, you must specify the address of an FDB containing file name information, a LUN, and an 
event flag number. 


If the file to be renamed is open when the call to .RENAM is issued, that file is closed before the 
renaming operation is attempted. 


You must preset the following registers before calling this routine: 


RO Must contain the address of the FDB associated with the file with the original name. 


R1 — Must contain the address of the FDB containing the desired file name information, the LUN assignment, 
and the event flag. 


If the renaming operation is successful, a new directory entry is created and the original entry 
is deleted. If the operation is unsuccessful, the file is closed under its original name, and the 
associated directory is not affected. 


The .RENAM routine uses the absence of a value in location F.FNB + N.FID to indicate that 
-PARSE must be called to parse a file specification (an open file always has a nonzero value in 
F.FNB + N.FID). If neither a data-set descriptor nor a default filename block is present, .PARSE 
returns a null file name. The rename operation then produces a new file name of version “.;1.” If 
a wildcard (*) is part of the input file specification, wildcard processing like that described for the 
.FIND routine occurs. Wildcards are not allowed in an output file specification. 


Note 


The renaming process is merely a directory operation that replaces an old entry with a new entry. 
The file name stored in the file header block is not altered. 


-EXTND—File Extension Routine 


The .EXTND routine extends either contiguous or noncontiguous files. The file to be extended can 
be either open or closed. A call to the EXTND routine disables file truncation. You must explicitly 
call .TRNCL to truncate a file after you call EXTND. 


You must preset the following registers before calling the EXTEND routine: 


RO Must contain the address of the associated FDB. 
R1 Must contain a numeric value specifying the number of blocks to be added to the file. 


R2 Must contain the extension control bits, as appropriate. The possible bit configurations for controlling 
file-extend operations are detailed in Table 4-1. This table defines the bits in the low-order byte of R2. The 
high-order 8 bits of R2 (bits 8 to 15) are used with the 16 bits of R1 to define the number of blocks to be 
added to the file (see Note 1, which follows). 


NOTE: (Notes) 


1 FCS uses the contents of R1 and the high-order byte of R2 (bits 8 to 15) to perform 
the specified .EXTND operation. Thus, 24 bits of magnitude are available for 
specifying the number of blocks by which the file is to be extended. 


2 Ifa file previously had space allocated to it, a contiguous file extension by the 
-EXTND routine cannot be done. You can create a contiguous file by opening a new 
file with a zero allocation and by calling .EXTND to allocate the desired number of 
blocks. 


4.14 


File Control Routines 


3. When writing a new file using QIO$ macros, the task must explicitly issue .EXTND 
calls, as necessary, to reserve enough blocks for the file, or the file must be initially 
created with sufficient blocks. In addition, the task must put an appropriate value 
in the FDB for the end-of-file block number (F.EFBK) before closing the file or 
rewinding and reading it. 


4 If R2 contains 0, FCS defaults to noncontiguous allocation. 


In general, when FCS implicitly extends a file, it activates file truncation. See Section 4.14 for | 
information on how to turn off file truncation. When your program explicitly allocates space to a 
file, either with an OPEN$ or .EXTND, FCS turns off truncation. To turn off file truncation and 
close the file, call the following routines: 


1 Call the .EXTND routine. Set both Rl and R2 to 0. 
2 Issue the CLOSE$ macro. 


Tabie 4-1 R2 Control Bits for .EXTND Routine 


Value In Low-Order 


Byte of R2 Meaning 

0 Indicates that the file extent is to be noncontiguous. 

200 Indicates that the file extent is to be noncontiguous. This clears the contiguous file 
attribute. 

201 Indicates that the contiguous area is to be added to the file. This clears the 
contiguous file attribute. 

203 Indicates that the largest available contiguous area is to be added to the file if the 
desired file extent space is not available. This clears the contiguous file attribute. 

205 Indicates that this is the initial extent of the file. The file is to be contiguous. 

207 Indicates that the largest contiguous area up to the specified extend size is to be 
added to the file. The file is to be contiguous. 

210 Indicates that the file is to be extended by the default extend size for the volume. 


The extend is to be noncontiguous. 


211 Indicates that the file is to be extended by the default extend size for the volume. 
The extend is to be contiguous; whereas, the file is to be noncontiguous. 


. TRNCL—File Truncation Routine 


The .TRNCL routine truncates a file to the logical end of the file, deallocates any space beyond this 
point, and closes the file. 


The following register must be preset before calling this routine: 
RO Must contain the address of the associated FDB. 


The file must have been opened with both write and extend access privileges. Otherwise, the 
truncation will fail. 


The close operation will be attempted even if the truncation operation fails. If errors occur in both 
operations, the error code from the close operation will be returned. 


FCS turns on truncation when it extends a file. However, when your program explicitly calls the 
-EXTND routine, FCS turns off truncation. 
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File Deletion Routines 
FCS provides the .MMRKDL and .DLFNE routines for deleting files. 


NOTE: If you use the .MRKDL or .DLFNB routine to delete a file containing sensitive 
information, you should clear the file before closing it or reformat the disk to destroy 
the sensitive information. (Although the file is marked for deletion, the information 
physically remains on the volume until written over with another file, and this 
information could be analyzed by unauthorized users.) 


.MRKDL—Mark Temporary File for Deletion 


You use the .MRKDL routine to mark a temporary file for deletion—that is, a file created through 
the OPNT$W macro call (see Chapter 3). Such a file has no associated directory entry. 


A call to the .MRKDL routine is issued prior to closing a temporary file. The file so marked is then 
deleted when the file is closed. 


You must preset the following register before calling the .MRKDL routine: 


RO Must contain the address of the associated FDB. This FDB is assumed to contain the file identification, 
device name, and unit information of the file to be deleted. 


If the MRKDL routine is invoked while the temporary file is open, as is normally done, the 
file is deleted unconditionally when it is closed. This occurs even if the calling task terminates 
abnormally without closing the file. 


.DLFNB-—Delete File by Filename Block 


You use this routine to delete a file by filename block. The .DLFNB routine assumes that the 
filename block is completely filled; when called, it closes the file, if necessary, and then deletes the 
file. 


You must preset the following register before calling the .DLFNB routine: 
RO Must contain the address of the associated FDB. 


The .DLFNB routine operates in the same manner as the DELET$ macro call (see Chapter 3), but 


.DLFNB does not require any of the .PARSE logic and thus requires less memory than the normal 
DELETS$ function. 


Like the DELET$ operation, however, the .DLFNB operation fails if the file to be deleted is not 
open, and if an explicit file version number is missing from offset location N.FVER of the associated 
filename block. 


.CTRL—Device Control Routine 


You call the .CTRL routine to perform device-specific control functions. The following are examples 
of .CTRL device-specific functions: 


¢ Rewind a magnetic tape volume set. 
¢ Position to the logical end of a magnetic tape volume set. 
¢ Close the current magnetic tape volume and continue file operations on the next volume. 


¢ Space forward or backward n blocks on a magnetic tape. 
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¢ Rewind a file on a magnetic tape or a terminal (record-oriented device). 


¢ Clear the terminal end-of-file. 


You must preset the following registers before calling this routine to perform the first three bulleted 
items listed previously in this section. 
RO Must contain the address of the associated FDB. 
R1 Must contain one of the following function codes: 
* FF.RWD rewinds a magnetic tape volume set. 
* FF.POE positions to the logical end of a magnetic tape volume set. 


¢ FF.NV closes the current volume and continues file operations on the next volume of a magnetic tape 
volume set. 


R2 Must be set to 0. 

R3 Must be set to 0. 

When using .CTRL to space forward or backward, you must ensure that registers RO, R1, R2, and 
R3 contain the following values: 

RO Must contain the address of the associated FDB. 

R1 Must contain the value FF.SPC. 


R2 Must contain the number of blocks to space forward or backward. A positive number means space forward; 
a negative number means space backward. 


R3 Must contain 0. 


When using .CTRL to rewind a file, you must ensure that register Rl contains the value FF.RWF 
and that registers R2 and R3 contain 0. 


See Chapter 5 for an explanation of using .CTRL to accomplish magnetic tape device-specific 
functions. 


4.17 .FLUSH—Buffer Flush Routine 


The buffer flush routine (.FLUSH) writes the block buffer to the file being written in record mode. 
The .FLUSH routine also writes file attributes (including F EFBK and F.HIBK, the end-of-file and 
high-allocation block numbers) each time the routine is called. 


Closing the file guarantees that the block buffer is flushed and that the file attributes will be 
written back to the file header. However, closing and opening a file frequently, solely to write the 
block buffer, causes high system overhead and unnecessary disk accesses. 


4.17.1 Purpose of the .FLUSH Routine 


When FCS executes a PUT$ macro to a disk file, the PUT$ macro puts a record into the block 
buffer. When the block buffer is full, or the file is closed, FCS writes the block buffer to the file. 
You cannot predict when FCS will actually write the block buffer to the file. 


Some applications may require that a record be written to a file immediately. As an example, 

a task that handles a laboratory device may write small amounts of data to a file every few 
minutes. If the system crashes, the contents of the block buffer may not have been written to 
the file. This data may be lost unless a PUT$ is immediately followed by a call to the FLUSH 
routine. As another example, the .FLUSH routine should be called by an originating task to write 
data immediately if another task must then read data written by that originating task. In these 
examples, the tasks need not close the file to ensure that the data is written to the file. 
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When .FLUSH Should Be Used 
Your task should call .FLUSH whenever data should be immediately written to a file. 


You need not call the .FLUSH routine for block mode (WRITE$) or record mode (PUT$) write 
operations to a record-oriented device; the block buffer is always written in these cases. Nothing 
happens if you call .FLUSH when a file is open under these circumstances except the return of a 
cleared Carry bit and status +1 (success) in FDB byte F.ERR. 


Performance Considerations Using .FLUSH 


Calling the .FLUSH routine after every PUT$ macro can greatly increase I/O activity compared to 
using solely the PUT$ macro. One alternative is to call the FLUSH routine after certain intervals 
have passed or after a certain number of calls to PUT$. 


Using the .FLUSH Routine 
You must preset the following register before calling this routine: 
RO Must contain the address of the associated FDB. 


During output, all registers are preserved, the Carry bit is clear or set to indicate success or 
failure, and the FDB F.ERR byte contains the success or failure code. 
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This chapter describes the structure of files supported by the IAS system. Specifically, this chapter 
covers the identical file structure that exists on disk, DECtape, and DECtape II. In addition, it 
also describes the American National Standards Institute (ANSI) file structure on magnetic tape 
supported by IAS. 


The disk, DECtape, and DECtape II file structure is called FILES-11; the magnetic tape file 
structure is ANSI standard. 


The FILES-11 structure is a file-organization system, which primarily determines the way that 
files and their associated control files are arranged on a disk or DECtape. FILES-11 structure 
includes not only the physical file and its associated control files, but it also includes the necessary 
information in these files that determines the file’s size, location, content, and various attributes. 


The ANSI standard describes a way of organizing sequential files on a magnetic tape that allows 
the tape to be used on any computer system. The standard includes file structure, labeling, and 
physical characteristics such as end-of-tape length. 


Disk and DECtape File Structure (FILES-11) 


Disk and DECtape volumes (defined by and associated with a VCB) contain both user files and 
system files. Disks and DECtapes initialized to FILES-11 structure have the standard FILES-11 
structure built for them. The standard system files created by these commands include the 
following: 


°¢ Index file 

¢ Storage allocation file 

¢ Bad block file 

¢ Master File Directory (MFD) 

¢ Checkpoint file 

Each FILES-11 volume has all of these files. A volume can have more than one directory 


file, the system uses these files, created by the MCR command UFD or the DCL command 
CREATE/DIRECTORY for IAS, to locate user files on the volume. 


User File Structure 


Data files on disk and DECtape consist of ordered sets of virtual blocks; these blocks constitute the 
virtual structure of the data files as they appear to you. Virtual blocks can be read and written 
directly by issuing READ$ and WRITE$ macro calls (see Chapter 3). The first block in the file is 
virtual block 1; subsequent virtual blocks are numbered in ascending order. 


The virtual blocks of a file are stored on the volume as logical blocks. Because virtual blocks and 
logical blocks are equal in size, and the logical block size of all volumes is 256 words, each virtual 
block is also 256 words. When access to a virtual block is requested, the virtual block number 

is mapped into a logical block number. The logical block number is then mapped to the physical 
address on the associated volume. 
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Directory Files 


A directory file contains directory entries. Each entry consists of a file name and its associated file 
number and file sequence number. The number of required directory files depends on the number 
of users of the volume. For single-user volumes, only an MFD is needed; for multiuser volumes, an 
MED is required, and one User File Directory (UFD) is required for each user of the volume. 


The MFD contains a list of all the UFDs on the volume, and each UFD contains a list of all that 
user’s files. UFDs are identified by User Identification Codes (UICs). You can create a UFD by 
using either MCR or DCL. The following example shows how to create a UFD by using the MCR 
command UFD: 


MCR>UFD DL1: [10,5] 
The next example shows how to create a UFD by using the DCL command CREATE/DIRECTORY. 
PDS>CREATE/DIRECTORY DU2: [LINDSEY] 


These commands are described in detail in the JAS MCR User’s Guide and the IAS Command 
Language Reference Manual. 


Figures 5—1 and 5—2 illustrate the directory structure for single-user and multiuser volumes, 
respectively. 


Index File 


You create the index file for the operating system to use when you initialize a volume. During 
initialization, the information required by the system to manage the file is placed in the index 
file. The index file contains volume information and user file header blocks, which the system file 
control primitives use to manage the file. The file header blocks (see Section 5.1.4) are stored in 
the index file so that they can be located quickly. Furthermore, because a file header block is 256 
words in length, it can be read into memory with a single access. Appendix E contains a detailed 
description of the format and content of an index file. 


Figure 5-1 Directory Structure for Single-User Volumes 
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Figure 5-2 Directory Structure for Multiuser Volumes 
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File Header Block 


Each file has a file header block that contains a description of the file. File header blocks are 
stored in the index file. Each file header block is 256 words long and contains the header area, 
the identification area, and the map area. Figure 5-3 illustrates the file header block and its 
contents. 


UFD 
[200,200] 


The header area identifies the block as a file header block. Each file is uniquely identified by a 
file ID consisting of two words. FILES-11 ACP (F11ACP) uses the first word of the file ID (that 
is, the file number) to calculate the virtual block number of that file’s header block in the index 
file. (This calculation is done as follows: the virtual block number is the file number plus 2 plus 
the number of index file bit map blocks.) F11ACP uses the second word (that is, the file sequence 
number) to verify that the header block is really the header for the desired file. 


When you request file access, both the file number and the file sequence number are specified. The 
system denies a request for access if the file sequence number does not match the corresponding 
field in the file header block that is associated with the specified file number. 


When you delete a file, its file header block space becomes available for storing a newly created 
file’s sequence number. If you attempt to access a file by file ID or by referencing an obsolete 
directory entry, this updated file sequence number ensures the rejection of the request for access. 


The identification area specifies the file’s creation name and identifies the file owner’s UIC. This 
area also specifies the creation date and time, the revision number, the date and time of the last 
revision, and the expiration date. 


The map area provides the information needed by the system to map virtual block numbers to 
logical block numbers. 
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Figure 5-3 File Header Block 
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Checksum Word 


A checksum value is computed each time the file header block is read from or written to the 
volume, thus ensuring that the file header block is transferred correctly. Appendix C contains a 
detailed description of the format and content of the file header block. 


Magnetic Tape File Processing 


IAS supports the standard American National Standards Institute (ANSI) magnetic tape structure 
as described in “Magnetic Tape Labels and File Structure for Information Interchange,” ANSI 
X3.27-1978. Any of the following file/volume combinations can be used: 


¢ Single file on a single volume 
e Single file on more than one volume 
¢ Multiple files on a single volume 


¢ Multiple files on more than one volume 


In the preceding list, the second and fourth file and volume combinations constitute a volume set. 


The record format on magnetic tape differs from that on disk. When a file containing 
variable-length records or fixed-length records that cross block boundaries is copied to magnetic 
tape, it occupies more blocks on the magnetic tape than it did on the disk. This is so because 
magnetic tape record counts are larger than disk record counts, and there is unused space at the 
end of the blocks. In addition, a bit is set in the file’s File Descriptor Block (FDB) that indicates 
the file cannot cross block boundaries. 
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Appendix G defines the sequence in which volume and file labels are used and the format of each 
label type. 


NOTE: The ANSI file header label contains no place for the creation time or the length 
of the file. Consequently, the creation time of a file on ANSI magnetic tape is listed as 
0. If a contiguous file is copied to ANSI magnetic tape and is then transferred back to 
disk, the resulting disk file is not marked as contiguous even if you use the /CO switch, 
because the system cannot know how much space to allocate for the output file when it 
reads from magnetic tape. 


Access to Magnetic Tape Volumes 


Magnetic tape is a sequential access, single-directory storage medium. Only one user can have 
access to a given volume set at a time. Only one file in a volume set can be open at a time. The 
system protects access by volume set rather than by file. On volumes produced by DIGITAL 
systems, the contents of the owner identification file determine user access rights as described in 
Appendix G. Volumes produced by non-DIGITAL systems are restricted to read-only access unless 
the access is overridden explicitly at MOUNT time. 


Rewinding Volume Sets 


You can rewind a magnetic tape volume set either by using the FDOP$R macro before an OPEN$ 
or CLOSE$ macro or by using the .CTRL file control routine. Regardless of the method you use, 
FCS performs the following procedures: 


1 All mounted volumes are rewound to the beginning-of-tape (BOT). 
2. If the first volume in the set is not mounted, the device unit to be used is placed off line. 


3. If the volume is not already mounted and if the rewind was requested with an OPEN$ macro 
or by a .CTRL routine call, a request to mount the first volume appears on the operator’s 
console. 


4 If the rewind was requested with a CLOSE$ macro, no mount message is issued until the next 
volume is needed. 


Positioning to the Next File Position 


The standard procedure for writing a new file onto a magnetic tape is to begin writing the file 
following the end of the volume set’s last file. However, you can use the FDOP$R macro to indicate 
that the new file is to be written immediately after the labels at the end of the most recently closed 
file. 


NOTE: The next file position option causes the loss of any files physically following this 
most recently closed file in the volume set. 


If, in addition to the next file position option, the rewind option also is specified, the 
file is created after the VOL1 label on the first volume of the set. All files previously 
contained in the entire volume set are lost. 


To create a file in the next file position, FA.POS must be set in FDB location FACTL. The default 
value for this FDB position is 0 (not FA.POS). The default indicates that the file system is to 
position itself at the logical end of the volume set to create the file. 
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When you use the default, the file system makes no check for the existence of a file with the same 
name in the volume set. Therefore, a program written to use magnetic tape normally should 
specify FA.POS, 


Directory device file processors ignore the next file position option. However, programs written 
mainly for directory devices can specify the next file position option in open commands for output 
and, therefore, override a process of positioning the file system to the logical end-of-file normally 
used with ANSI magnetic tape. 


Single-File Operations 


You perform single-file operations by specifying the rewind option with the FDOP$R macro before 
the open and before the close. Using this approach, you can perform operations on temporary tapes 
or work tapes (scratch tapes) as follows: 


Open the first file with the rewind option specified. 
Write the data records and close the file with rewind. 
Open the first file again for input (rewinding is optional). 
Read and process the data. 

Open the second file with rewind specified. 

Write the data records. 


Close the file with rewind and perform any additional processing. 


N Oo GO & DOD ND = 


Multifile Operations 


You create a multifile volume by first opening and writing and then closing a series of files without 
specifying the rewind option. You can process files sequentially on the volume by closing without 
rewind and by opening the next file without rewind. 


Opening a file for extend with the OPEN$A macro is legal only for the last file on the volume set. 
Perform the following tape operations to create a multifile tape volume: 

Open a file for output with the rewind option. 

Write data records and close the file. 

Open the next file without rewinding. 

Write the data records and close the file. 
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Repeat for as many files as desired. 


You can open files on tape in a nonsequential order, but doing so increases processing and 
tape-positioning time. Nonsequential access of files in a multifile volume set is not recommended. 
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Using .CTRL 


You can call the .CTRL file control routine to override normal FCS defaults for magnetic tape. This 
routine might be used to perform the following tasks: 


e Continue processing a file on the next volume of a volume set before the end of the current 
volume is reached. 


¢ Position to the logical end-of-volume set. 

¢ Rewind a volume at other times than when opening or closing the file. 
e Space forward or backward any number of records. 

¢ Rewind a file. 


When FCS uses the .CTRL routine to continue processing a file on the next volume, the first file 
section on the next volume is opened. File sections occur when a file is written on more than one 
volume. The portion of the file on each of these volumes constitutes a file section. For input files, 
the following .CTRL routine processing occurs: 


1 If the current volume is the last volume in the set (that is, there is no next volume), the 
end-of-file is reported to you. 


2 If another file section exists, the current volume is rewound and the next volume is mounted. 
A request to mount the next volume appears on the operator’s console. 


3 The header label (HDR1) of the next file section is read and checked. 
4 If all required fields check, the operation continues. 


5 If any check fails, the operator is requested to mount the correct volume. 


For output files, the following .CTRL routine processing occurs: 
1 The current file section is closed with EOV1 and EOV2 labels and the volume is rewound. 
2 The next volume is mounted. 


3 A file with the same name and the next higher section number is opened for a write operation. 
The file set identifier is identical with the volume identifier of the first volume in the volume 
set. 


NOTE: I/O buffers that are currently in memory are written on the next file section. 


When the .CTRL routine positions the tape to the logical end of the volume, the file system 
positions the tape between the two tape marks at the logical end of the last volume in the set. 


When the .CTRL routine spaces forward or backward across blocks on magnetic tape, spacing 
crosses volumes for multivolume files. 


Examples of Magnetic Tape Processing 


The following sections contain examples of FCS statements that process magnetic tape. Macro 
parameters not related to magnetic tape handling are omitted from these statements. 
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5.2.7.1 Examples of OPEN$W Macro-11 Statements to Create a New File 


All routines expect RO to contain the FDB address. For example: 


OPRWDO: 

; OPEN WITH REWIND 
FDOPS$R_ RO,,,,,#FA.ENB!FA.RWD ;SET REWIND AND ENABLE USE 
BR OPNOUT ;OF F.ACTL 

OPNXTO: 


; OPEN FOR NEXT FILE POSITION 


° 
‘ 


FDOPSR RO,,,,,#FA.ENB!IFA.POS  ;SET POSITION TO NEXT 
BR OPNOUT ;AND ENABLE USE OF F.ACTL 
OPROYK: 
; OPEN FILE AT END OF VOLUME KEEPING CURRENT USER 
; ACCESS CONTROL BITS 
BIC #FA ENB, F .ACTL(RO) ;DISABLE USE OF F.ACTL 
BR OPNOUT 
OPROVO: 
; OPEN FILE AT END OF VOLUME - SELECT SYSTEM DEFAULT FOR 
; USER ACCESS CONTROL BITS 
FDOPS$R RO,,,,,#0 ;DISABLE USE OF AND RESET 
BR OPNOUT :F.ACTL TO ZERO 


7 OPEN FILE WITH CURRENT USER ACCESS CONTROL 


OPOURO: 


BIS #FA.ENB, F.ACTL (RO) ;ENABLE USE OF F.ACTL 
OPNOUT: FDBFSR_ RO, , #8192. ; OVERRIDE BLOCK SIZE FOR TAPE 
OPENSW- RO 
RETURN 
5.2.7.2 Examples of OPEN$R Macro-11 Statements to Read a File 


All routines expect RO to contain the FDB address. For example: 


OPRWDI: 


° 
tf 


; OPEN WITH REWIND 
FDOPSR RO,,,,,#FA.ENB!FA.RWD 
BR OPNIN 

OPCURI: 


OPEN STARTING SEARCH AT CURRENT TAPE POSITION KEEPING USER 
ACCESS CONTROL BITS 


“eo Ne Ne Ne 


BIC #FA. ENB, F.ACTL(RO) ;DISABLE USE OF F.ACTL 
BR OPNIN 


; OPEN USING USER ACCESS CONTROL 


. 
, 


OPDFLI: BIS #FA.ENB,F.ACTL (RO) 7;ENABLE USE OF F.ACTL 

OPNIN: FDBFSR_ RO,, #2048. ;OVERRIDE BLOCK SIZE FOR TAPE 
OPENSR- RO 
RETURN 
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Examples of CLOSE$ Macro-11 Statements 


All routines expect RO to contain the FDB address. For example: 


CLSCUR: 


USER ACCESS CONTROL BITS 


se “Me Ne Ne 


BIC #FA.ENB, F.ACTL (RO) 
BR CLOSE 


CLSRWD: 


CLOSE REWINDING THE VOLUME 


"e Ne Ne 


FDOPSR_ RO,,,,,#FA.ENB!FA.RWD 
BR CLOSE 


CLOSE WITH USER ACCESS CONTROL BITS 


™e Ne Ne 


CLSDFL: BIS #FA.ENB,F .ACTL(RO) 
CLOSE: CLOSES RO 
RETURN 


5.2.7.4 


CLOSE LEAVING TAPE AT CURRENT POSITION AND KEEPING 


;DISABLE USE OF F.ACTL 
;DEFAULT IS LEAVING AT CURRENT 
7 POSITION 


;SET REWIND AND ENABLE USE OF 
7F.ACTL 


;ENABLE USE OF F.ACTL 


Combined Examples of OPEN$ and CLOSE$ Macro-11 Statements 


The following examples call routines shown in previous examples in Section 5.2.7.1. By combining 
various magnetic tape operations, you can process tape volumes in the following ways: 


;SELECT FDB AND OPEN 
;OUTPUT FILE WITH REWIND 


;SELECT FDB AND OPEN FOR 
; INPUT WITH REWIND 


7CLOSE SCRATCH FILE 
;REWINDING VOLUME 


OPEN FILE FOR READING WHEN FILE IS NEXT OR FURTHER UP THE VOLUME 


;SELECT FDB 
;OPEN FILE 


; SCRATCH TAPE OPERATIONS--SINGLE FILE VOLUME-- 
SCROUT: MOV #FDBOUT, RO 
CALL OPRWDO 
RETURN 
SCRIN: MOV #FDBIN, RO 
CALL OPRWDI 
RETURN 
CLSCRO: MOV #FDBOUT, RO 
BR CLSVOL 
CLSCRI: MOV FDBIN, RO 
CLSVOL: CALL CLSRWD 
RETURN 
; MULTI-FILE VOLUME OPERATIONS 
OPNXTI: 
? 
? 
MOV #FDBIN, RO 
CALL OPCURI 
RETURN 
OPENIN: 


e 
, 


; OPEN FILE FOR READING WHEN POSITIONED 


MOV #FDBIN, RO 
CALL OPRWDI 
RETURN 


MULTI-FILE OUTPUT OPERATIONS 


“eo Ne Ne 


PAST IT 


7;SELECT FDB 


5-9 


File Structures 


OPNINT: 


START NEW VOLUME DESTROYING ALL PAST FILES ON IT 


Se Ne Ne 


MOV #FDBOUT, RO ;SELECT OUTPUT FDB 
CALL OPRWDO 7;OPEN WITH REWIND 
RETURN 


OPNEXT: 


OPEN OUTPUT FILE AT NEXT FILE POSITION DESTROYING ANY FILE 
THAT MIGHT BE AT OR PAST THAT POSITION 


we Me Se Ne 


MOV #FDBOUT, RO ;SELECT OUTPUT FDB 
CALL OPNXTO 
RETURN 


OPENDT: 


OPEN OUTPUT FILE AT CURRENT END OF VOLUME SET KEEPING USER 
ACCESS CONTROL BITS 


‘we Ne Ne 


MOV #FDBOUT, RO ;SELECT OUTPUT FDB 
CALL OPROVK 
RETURN 


OPNEOV: 


OPEN OUTPUT FILE AT CURRENT END OF VOLUME AND MAKE THAT THE USER 
ACCESS CONTROL 


“ae Me Se Ne 


MOV #FDBOUT, RO ;SELECT OUTPUT FDB 
CALL OPROVO 
RETURN 
; NOT LAST FILE IN FILE SET CLOSE ROUTINE 
CLSFLO: MOV #FDBOUT, RO _-«g SELECT OUTPUT FDB 
BR CLSXX 
CLSFLI: MOV #FDBIN, RO ;SELECT INPUT FDB 
CLSXX: CALL CLSCUR 
RETURN 


TO APPEND TO LAST FILE 


OPENSA #FDBOUT 
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Command Line Processing 


This chapter describes two object library routines that are available from the system object library, 
[1,1JSYSLIB.OLB. These routines may be linked with your task to provide the logical capabilities 
necessary to process terminal command line input as follows: 


Get Command Line (GCML) Accomplishes all the logical functions associated with the entry of 
command lines from a terminal, an indirect command file, or an online 
storage medium. Using GCML relieves you of the burden of manually 
coding command line input operations. 

Command String Interpreter (CSI) Takes command lines from the GCML command line input buffer and 
parses them into the appropriate data-set descriptors that FCS requires 
for opening files. 


The Task Builder (TKB) links these routines with your program when the task is being built. 
GCML and CSI are often used together in system or application programs as a standardized 
interface for obtaining and interpreting dynamic command line input. Figure 6—1 shows the flow 
of data during command line processing. 


Although this chapter assumes the joint use of these routines to process command line input, 
GCML and CSI may be used independently. Using one without the other, however, requires that 
you manually code the functions normally performed by the missing component. 


Invoking GCML and CSI functions requires that certain initialization be done when you write 
the source code. This initialization sets up the GCML command line input buffer, defines and 
initializes control blocks for both GCML and CSI, and establishes the necessary working storage 
and communication areas for these routines. Also, the appropriate macro calls that invoke GCML 
and CSI execution-time functions must be included in the source code at appropriate logical points 
to effect the dynamic processing of command lines. 


GCML and CSI macro calls observe the same register conventions as File Control Services (FCS). 
All registers except RO are preserved exactly as those in FCS macro calls. RO contains the address 
of the GCML control block or the CSI control block, as appropriate. 


As with all FCS macro calls, the GCML and CSI macro calls must be listed as an argument in a 
-MCALL directive (see Chapter 2) before you insert them in your program. 


Get Command Line (GCML) Routine 


The Get Command Line (GCML) routine contains all the logical capabilities necessary to enter 
command lines dynamically during program execution. GCML accepts input from a terminal or an 
indirect command file that contains predefined command lines. If your program allocates sufficient 
buffer space in the file storage region (FSR) (see Chapter 2), GCML accepts commands that are 
longer than one line of terminal input. The appearance of a hyphen (-) as the last printing 
character of a command line permits the continuation of commands from one line to the next. 


All GCML functions require you to create and initialize a GCML control block. See Section 6.1.1 
for a description of this macro call. The GCML runtime macro calls that your task may issue 
dynamically are described in Section 6.1.3. 
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Figure 6-1 Data Flow During Command Line Processing 
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6.1.1 GCMLB$—Allocate and Initialize GCML Control Block 


This section describes the GCMLB$ macro. This macro is a necessary part of the code needed 
to dynamically obtain and execute command lines. During the assembly of your program the 
GCMLB$ macro performs the following tasks: 


e Reserves storage for and initializes a GCML control block within your program. 


* Creates and initializes an File Descriptor Block (FDB) for the indirect command file in the fir 
part of the GCML control block. 
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¢ Creates and initializes a default filename block within the GCML control block. 


¢ Defines the symbolic offsets for the GCML control block and initializes certain offsets to 
required values by invoking the GCMLD$ macro. These offsets are described in detail in 
Section 6.1.2. 


FCS uses the FDB to open an indirect command file. Your program may open and read a command 
file, which can use a terminal or a file-structured device such as a disk. GMCL and FCS initialize 
and maintain this FDB. 


FCS uses the default filename block for an indirect command file. If you do not specify an explicit 
filename string for an indirect command file, the values CMI for the file name and .CMD for the 
file type are assumed by default. There is no default designation for the device name. 


label: GCMLB$ maxd,prmpt,ubuf,lun,pal,size 


Parameters 


label 

Specifies a symbol] that names the GCML control block and defines its address. This label permits 
the GCML control block to be referenced directly by all the GCML runtime routines that require 
access to this structure (see Section 6.1.3. 


maxd 


Specifies a numeric value that specifies the maximum nesting depth permitted for indirect 
command files. This parameter determines the number of nested indirect command files that 
GCML can access when obtaining command line input. 


An indirect command file, which often resides on disk, contains well-defined, nonvarying command 
sequences, which may be read directly by GCML to control such highly repetitive operations as 
TKB activities. 


If you do not specify this parameter, the default nesting level depth is 0, which effectively 
eliminates an indirect command file as a source of command line input. 


prmpt 

Specifies a 3-character American Standard Code for Information Interchange (ASCII) prompting 
sequence that you specify. The GCML routine displays this default prompt string at your terminal 
to solicit command line input. 


The ASCII prompting sequence is constructed as the following 6-byte string: 
¢ Acarriage return (<CR>) and a line feed (<KEY>(LF\ TEXT)) 

¢ The three ASCII characters that you specify 

¢ A right angle bracket (>) 


The ASCII prompting sequence initializes GCML control block offset location G.DPRM (see 
Section 6.1.2. 


If you do not specify this parameter, GCML uses the right angle bracket preceded by three blanks 
as the default prompting sequence. 


ubuf 

Specifies the address of a buffer that the GCML routine uses for temporary storage of command 
line input. If you do not specify this parameter, a buffer is reserved in the GCML control block for 
command line input. The size parameter determines the length of the buffer. If you specify neither 
this parameter nor the size parameter, a 41-word buffer is reserved by default in the GCML control 
block. 
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lun 
Specifies a logical unit number (LUN). The GCML routine uses the device assigned to this LUN as 
the command input device. If you do not specify this parameter, GMCL uses a LUN of 1 by default. 


pdl 

Specifies the address of an area reserved in your program as a push-down list. Indirect command 
file processing uses this area for working storage. Normally, you do not specify the pdl parameter 
unless you want to increase the storage for the push-down list. 


Statements logically equivalent to the following create the push-down list: 


- EVEN 
label: .BLKB G.LPDL 


The label that you supply specifies the push-down list and defines its address. G.LPDL, which is 
defined by the GCMLB$ macro, is the length (in bytes) of the push-down list. 


The length of the push-down list is a function of the maximum number of nested indirect command 
files that may be accessed by GCML in obtaining command line input. You can increase the storage 
in the control block for the push-down list by calculating the value according to the following 
algorithm: 


1 Add 1 to the maximum nesting level depth declared with the maxd parameter described 
previously. 


2 Multiply the sum of step 1 by 1619 to find the number of bytes that must be reserved for the 
push-down list. 


For example, if you specify 4 as the maxd parameter, you determine the length of the push-down 
list as follows: 


(441) *16. = 8019 bytes 


From the previous mathematical statement, note that 16,9 bytes of storage are required for each 
indirect command file (4), plus another 16,9 bytes as general overhead. 


size 

Specifies the size, in bytes, of the buffer reserved for command line input. The size must always 
include two extra bytes that are used internally by GCML. The default size value is 82 (that is, 80 
bytes for command line input and 2 bytes GCML overhead). 


If you want GCML to accept continuation lines, the specified value for the size parameter must be 
greater than 82. When the size is greater than 82, the bit value GE.CON is set in the status and 
mode control byte (offset G-MODE) of the GCML command block. This value indicates that the 
continuation mechanism is in effect. 


Example 


GCLBLK: GCMLBS$ 4.,GCM,BUFADR,1. 
GCLBLK: GCMLBS$ ,,BUFADR 
GCLBLK: GCMLB$ DEPTH, GCM, BUFADR, CMILUN, PDLIST, BUFSIZ 


Illustrates how a GCMLB$ macro call may be used in a program. 
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GCMLD$—Define GCML Control Block Offsets and Bit Values 


The GCMLD$ macro, which the GCMLB$ macro call invokes, locally defines the GCML control 
block offsets and bit values within the current module. Table 6—1 describes these offsets and their 


bit values. 


Table 6-1 GCML Offsets and Bit Values 


Symbolic 
Offset 
Name 


G.ERR 


G.MODE 


Description 


Error return code byte 


This field initially contains 0. If any error conditions that GCML recognizes occur during the 
processing of a command line, an appropriate error code is returned to offset location G.ERR 
in the control block. Descriptions of these error bits follow: 


GE.IOR—1/O error occurred during the input of a command line. 
3E,.OPR—GCML unable to open or reopen the specified command file. 
GE.BIF—Syntax error detected in the name of the indirect command file. 


GE.MDE—Attempt made to exceed the maximum permissible nesting-level depth for an indirect 
command file (see the description of the maxd parameter in Section 6.1.1). 


GE.RBG—Command line input buffer was too small for the total command. This condition can occur 
when multiple lines have been entered using the continuation mechanism. The input buffer contains 
as much of the command as possible. 


GE.EOF—End-of-file (EOF) on the top-level command file detected. 


NOTE: For GE.IOR and GE.OPR, additional information concerning the 
error is available by examining the FCS error code at offset FERR from the 
start of the GCML block. 


The error code is set along with command file input. When the first call is issued for input, GCML 
attempts to retrieve a Monitor Console Routine (MCR) command line. Command level 0 is set 
for the first line obtained, whether it is an MCR command or a terminal command. If the name of 
an indirect command file is then entered, the command input level is increased to 1. Therafter, 
each indirect command file name entry increments the command input level. When the EOF is 
encountered on any given indirect command file, the command input level is decremented by 1, 
restoring the count to the previous level and reopening the associated command file. The next 
command line from that file is ther read. 


If an MCR command has already been read at level 0, entering another MCR command when level 
0 is again reached causes the error code GE.EOF to be returned to offset location F.ERR of the 
GCML control block. Hence, only one MCR command line can be read at level 0. If input falls at 
MCR level 0, then GCML continues to prompt for input until you press CTRL/Z to indicate terminal 
EOF. 


In summary, the first line of input is always read at level 0. This initial input may be an MCR 
command; if the MCR command fails or is null, the command input file (normally a terminal) is then 
opened at level 0. Multiple inputs at level 0 are permissible only in the latter case, that is, from the 
command input file. 


Status and mode control byte 


This field is initialized at assembly time with bit definitions to specify certain default actions for 
GCML during the retrieval of a command line. 
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Table 6-1 (Cont.) GCML Offsets and Bit Values 


Symbolic 


Offset 
Name 


Description 


G.PSDS 


G.CMLD 


At run time, you can reset default status and mode control bits by issuing a bit clear byte (BICB) 
instruction that takes the symbolic name of the bit to be cleared as the source operand. In the case 
of the GE.LC value (see the following text), the BICB instruction can override the default action. 


Descriptions of the symbolic names of the bits defined in the status and mode control byte follow: 


GE.IND—(Default) A command line that begins with a leading at sign (@) is an explicit indirect 
command file specification. If you reset the GE.IND bit to 0, a command line beginning with an at 
sign is returned to the calling program. 


GE.CLO—(Default) The command file currently being read is closed after each GCML$ macro call 
is issued. If you reset the GE.CLO bit to 0, GCML keeps the current command file open between 
calls for input. In this case, the file storage region (FSR) described in Chapter 2 must include one 
additional 512;9-byte buffer for command line input. This requirement adds to the total FSR block 
buffer space normally reserved for the maximum number of files that may be open simultaneously 
for record I/O processing. 


Clearing the GE.CLO bit in the status and mode control byte renders 5121) bytes of FSR block 
buffer space unavailable for other purposes because the command file remains open between calls 
for command line input. 


GE.COM—{Default) A command line that begins with a leading semicolon (;) is a comment. Such 
lines are not returned to the calling program. If you reset this bit to 0, a command line beginning 
with a leading semicolon is returned to the calling program. 


GE.CON—If the value of the size parameter of the GCMLB$ macro is greater than 82, the 
continuation mechanism is in effect by default. You must not attempt to set this bit in the mode 
byte without providing a buffer larger than 82 bytes. 


GE.LC—If this bit is set to 1 in the GCML control block at run time, lowercase characters in the 
command line are passed unaltered to your program. If this bit is not set, lowercase characters are 
changed to upppercase before being passed to your program. 


Prompt string descriptor 


Initialize this 2-word field to 0 at assembly time by issuing the GCMLB$ macro call (see 
Section 6.1.1). 


When you issue the GCML$ macro call to request command line input (see Section 6.1.3.1), the 
address and the length of a prompting sequence are usually not specified. In this case, the prompt 
string descriptor words in the GCML control block are cleared, causing GCML to type out the 
default prompt string contained in offset location G.DPRM to solicit command line input. (See the 
description of G.DPRM in the following text.) 


If you want to define an alternate prompt string elsewhere in the program, you may do so through 
the .ASCIl directive. The address and length of this alternate prompt string may then be specified 
as the adpr and Inpr parameters in subsequent GCML$ macro calls. (See the description of these 
parameters and how they affect alternate prompt strings in the following text.) These parameters 
cause Offset locations G.PSDS+2 and G.PSDS to be initialized with the address and the length, 
respectively, of the alternate prompt string. GCML then types out the alternate prompt string to 
solicit command line input, thereby overriding the default prompt string previously established 
through the GCMLB$ macro call. 


If you do not specify the adpr and Inpr parameters in a subsequent GCML$ macro call, offset 
location G.PSDS in the control block is reset to 0, causing GCML to revert to the use of the default 
prompt string contained in offset location G.DPRM. 


Command line descriptor 
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Table 6-1 (Cont.) GCML Offsets and Bit Values 


Symbolic 
Offset 
Name Description 


GCML. initializes this 2-word field after retrieving a command line. The address of this command line 
is returned to offset location G.CMLD+2, and the length (in bytes) of the command line is returned 
to offset location G.CMLD. 


The contents of these word locations in the GCML control block may be passed to the Command 
String Interpreter (CSI) as the buff and len parameters in the CSI$1 macro call (see Section 6.2.3.1). 
The combination of these parameters constitutes the command line descriptors that enable CSI to 
retrieve file specifications from the GCML command line input buffer. 


G.ISIZ Impure area size indicator 


This symbol is defined at assembly time, indicating the size of an impure area within the GCML 
control block to be used as working storage for pointers, flags, counters, and so forth, along with 
input from an indirect command file. In normal usage, you need not be concerned with this symbol. 


The space between the FDB ancl the default prompt string (see G.DPRM in the following text) is 
the impure area of the GCML control block. The value of the symbol S.FDB defines the size of the 
FDB. Thus, the size of the impure area is equal to GIDPRM minus S.FDB (G.DPRM-S.FDB). 


G.DPRM Default prompt string 


This 6-byte field is initialized at assembly time with the default prompt string created through the 
prmpt parameter of the GCMLB$ macro call (see Section 6.1.1). In the absence of the adpr and 
Inpr parameters in the GCML$ macro call (see Section 6.1.3.1), GMCL types out this default prompt 
string to solicit terminal input. 


You can reference the GCML control block offsets and bit values in another module by establishing 
the appropriate symbolic definitions within that module through one of the following statements: 


GCMLDS$ 7;DEFAULT LOCAL DEFINITION 
GCMLD$ DEFSL 7 LOCAL DEFINITION 
GCMLD$ DEFSG 7GLOBAL DEFINITION 


GCML Routine Runtime Macros 


GCML provides the following three runtime macro calls to perform specific functions: 


GCML$ Retrieves a command line. 
RCML$ Resets the indirect command file scan to the first (unnested) level. 
CCML$ Closes the current command file. 


These routines are described in the following sections. 


6.1.3.1 GCML$—Get Command Line Macro 


GCMLS§ serves as your program interface for retrieving command lines from a terminal or an 
indirect command file. You can issue this macro call at any logical point in the program to solicit 
command line input. 


GCML$ _  gclbik, adpr,inpr 
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Parameters 


gcibik 

Specifies the address of the GCML control block. This symbol must be the same as the symbol 
specified at assembly time in the label field of the GCMLB$ macro call (see Section 6.1.1). If you 
do not specify this parameter, RO is assumed to contain the address of the GCML control block. 


adpr 

Specifies the address of your program location containing an alternate prompt string. When this 
optional parameter and the Inpr parameter are present in the GCML$ macro call, the alternate 
prompt string appears on your terminal to solicit command line input. The normal default prompt 
string, as contained in offset location G.DPRM of the GCML control block (see Section 6.1.2), is 
thereby overridden. 


Inpr 
Specifies the length (in bytes) of the optional, alternate prompt string. If you do not specify this 
parameter, offset location G.PSDS in the GCML control block (see Section 6.1.2) is cleared. 


If you specify this parameter, but do not specify the adpr parameter described previously, an 
-ERROR directive is generated during assembly that causes the error message “Prompt string 
missing” to be printed in the assembly listing. This message is a diagnostic announcement of an 
incomplete prompt string descriptor in the GCML$ macro call. If you specify this parameter, as 
well as the adpr parameter, the default prompt string is overridden. 


If you do not specify the adpr and Inpr parameters in a subsequent GCML$ macro call, offset 
location G.PSDS in the GCML control block is reset to 0. Consequently, GCML reverts to using the 
default prompt string contained in offset location G.DPRM (see Section 6.1.2). 


When you issue the GCML$ macro call, the following occurs: 


1 RO is loaded with the address of the GCML control block. If you do not specify the gclblk 
parameter, RO is assumed to contain the address of the GCML control] block. If it does not - 
contain that address, you must first manually initialize RO with the address of the control 
block before you issue the GCML$ macro call. 


2 The address and the length of the alternate prompt string, if specified, are stored in control 
block offset locations G.PSDS+2 and G.PSDS, respectively. These two words constitute the 
alternate prompt string descriptor. 


3 Code is generated that calls GCML to transfer a command line to the command line input 
buffer. If the last character of an input line is a hyphen (-), and if the value GE.CON is 
present in the status and mode control byte, GCML transfers commands that are longer 
than one line. The continuation lines obtained are concatenated in the input buffer with the 
continuation hyphen or hyphens removed. 


When your task first issues the GCML$ macro call, GCML$ tries to retrieve an MCR command 
line. If this attempt fails, or if the MCR command line is null, GCML uses the FDB within the 
GCML control block to open a file for command line input. If the command input device is a 
terminal, a prompt string appears on your terminal to solicit input. Any appropriate command 
input may then be entered. If the continuation mechanism is in effect, the prompt string reappears 
to solicit subsequent portions of the continued command line. 


If appropriate, you may enter an at sign (@) as the first character in the command line, followed 
by the name of an indirect command file. This file name identifies an explicit indirect command 
file from which input is to be read. GCML then opens this file and retrieves the first command 
line. On successive GCML calls, this file is read until one of the following occurs: 
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¢ The end-of-file (EOF) is detected on the current indirect command file. In this case, the 
current indirect file is closed, the command input level count is reduced by 1, and the previous 
command file is reopened. If the command input level count is already 0 when EOF is detected, 
the error code GE.EOF is returned to offset location G.ERR of the GCML control block (see 
Section 6.1.2). 


e An indirect command file specification is encountered in a command line. In this case, the 
current indirect command file is closed (if not already closed), the new indirect command file is 
opened, and the first command line is read. 


e¢ An RCML$ macro call is issued in the program (see Section 6.1.3.2). In this case, the current 
indirect command file is closed, and the command input count reverts to level 0; that is, the 
top-level command file is again used for input. 


You may also enter a semicolon (;) as the first character in the command line. If GE.COM is set, 
such a line is treated as a comment and is not returned to the calling program. If GE.COM is 
clear, the line is returned to the calling program. 


Whether a command line is entered manually or retrieved from an indirect command file, the 
address and the length of the command line are returned to GCML control block offset locations 
G.CMLD+2 and G.CMLD, respectively. Together, these two words constitute the command line 
descriptors. These descriptors may be specified as the buff and len parameters in the CSI$1 macro 
(see Section 6.2.3.1). 


Successful retrieval of a command line causes the Carry bit in the Processor Status Word (PSW) to 
be cleared. Any error condition that occurs during the retrieval of a command line, however, causes 
the Carry bit to be set. In addition, a negative error code is returned to offset location G.ERR of 
the GCML control block. These error codes are described in detail in Section 6.1.2. 


Examples of how you may use the GCML$ macro in a program follow. 


Examples 
GCML$ #GCLBLK 

Specifies the symbolic address of the GCML control block. 
GCMLS$ 


Assumes that RO contains the address of the GCML control block. The preceding examples both 
employ the default prompt string contained in offset location G.DPRM of the control block to solicit 
command line input. 


GCML$ #GCLBLK, #ADPR, #LNPR 


Specifies the address and the length of an alternate prompt string that you have defined within 
the program. GCML uses this alternate prompt string to prompt for terminal input, rather than 
using the default prompt string contained in the GCML control block. 


6.1.3.2 RCML$—Reset Indirect Command File Scan Macro 


If you must close the current indirect command file and return to the top-level file, that is, to the 
top-level (unnested) file, you may do so by issuing the RCML$ macro. 


RCML$  gclbik 
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Parameter 


gclibik 
Specifies the address of the GCML control block. If you do not specify this parameter, RO is 
assumed to contain the address of the GCML control block. 


When you issue this macro, the current indirect command file is closed, returning control to the 
top-level (unnested) file. A subsequent GCML$ macro then retrieves the next command line from 
the 0-level command file. Note, however, that a second MCR command at level 0 cannot be read 
(see GE.EOF error code in offset location G.ERR of GCML control block, Section 6.1.2). 


Example 
RCML$  #GCLBLK 
RCMLS RO 


Illustrates how you may use the RCML$ macro in a program. This macro call requires only the 
address of the GCML control block. 


6.1.3.3 CCML$—Close Current Command File Macro 


You may want to close the current command file between calls for input to free FSR block buffer 
space for some other use. File Control Services (FCS) normally closes the command file after the 
retrieval of a command line, provided that the GE.CLO bit in the status and mode control byte 
remains appropriately initialized (see Section 6.1.2). This bit is set to 1 at assembly time. If you 
reset this bit to 0, the current command file remains open between calls for input. 


For a program that frequently reads command files, this may be a desirable operational mode, 
because keeping the file open between calls for input reduces total file access time. However, 
should you want to close such a file to free FSR block buffer space, you may do so by issuing the 
CCML$ macro call. 


CCML$ gclbik 


Parameter 


gclbik 


Specifies the address of the GCML control block. If you do not specify this parameter, RO is 
assumed to contain the address of the GCML control block. 


Issuing this statement closes the current command file, effectively releasing 512;9 bytes of FSR 
block buffer space for some other use between calls for input. If the command file is already closed 
when your task issues the CCML$ macro call, control is returned to your task. A subsequent 
GCML#$ macro call then causes the command file to be reopened and the next command line in the 
file to be returned to the calling program. 


Example 
CCML$ #GCLBLK 
CCML$ RO 


Illustrates how the CCML$ macro may be used in a program. As in the RCML$ macro call 


described previously, this macro call takes a single parameter, specifically, the address of the 
GCML control block. 


6.1.4 
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GCML Usage Considerations 


As noted in Section 6.1.1, the GCMLB$ macro call creates a File Descriptor Block (FDB) in the first 
part of the GCML control block. Although ordinarily you need not manipulate this FDB (because 
it is under GCML and FCS control), you can perform the following operations on this FDB: 


1 In an unrecoverable error situation, you can issue a CLOSE$ macro call (see Chapter 3) with 
the address of this FDB before issuing the system EXIT$ macro call. 


2 You can test the FD.TTY bit in the device characteristics byte (offset location F.RCTL) of the 
FDB to determine whether the command line just obtained was retrieved from a terminal. 


3 In the event that error code GE.IOR or GE.OPR is returned to control block offset location 
G.ERR (indicating that an I/O error has occurred during the retrieval of a command line), you 
can test offset location FERR of the associated FDB for a more complete error analysis. This 
FDB cell also contains an error code that may be helpful in determining the nature of the error 
condition. 


At task-build time, the Task Builder (TKB) device assignment (ASG) option should be issued to 
assign the appropriate physical device unit to the desired logical unit number (LUN). For example, 
to assign the LUN (lun parameter) in the GCMLB$ macro call (see Section 6.1.1) to a terminal, the 
following TKB option should be issued: 


ASG = TI:1 


The designation TI is a pseudo-device name that is redirected to the command input device. Note 
that the numeric value following the colon (:) must agree with the numeric value specified as the 
lun parameter in the GCMLB$ macro call. 


The ASG option is described in further detail in the JAS Task Builder Reference Manual. 


As covered in the discussion on FSRSZ$ (see Chapter 2), at any given time there must be an FSR 
block buffer available for each file currently open for record I/O operations. You must consider 
the buffer requirements of the command file when issuing the FSRSZ$ macro. (FSRSZ$ must be 
issued with a nonzero first parameter.) 


Command String Interpreter Routine 


The Command String Interpreter (CSI) routine analyzes command lines and parses them into their 
component device name, directory, and filename strings. You should be aware that CSI processes 
command lines in the following formats only: 


e §=6dev:[g,mJoutputfilespec/switch 


More than one file specification can be specified by separating the file specifications with 
commas. 


¢ dev:[g,m]Joutputfilespec/switch,...= dev:[g,m linputfilespec/switch,... 


A file specification may be either of the following: 
filename .type; version 

or 
"ANSI name string"; version 


CSI maintains a data-set descriptor within the CSI control block (see Section 6.2.1), which FCS 
can use when opening files. The runtime routines that analyze and parse command lines for your 
calling program are described in Section 6.2.3. 
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Using CSI requires that the CSI control block offsets and hit values be defined and that a control 
block be allocated within the program. The macro described in the following section accomplishes 
these requisite actions. 


CSi$—Define CSI Control Block Offsets and Bit Values Macro 


Following is the only initialization coding required for CSI at assembly time: 


CsI$ 7;DEFINES CSI CONTROL BLOCK OFFSETS 
7;AND BIT VALUES LOCALLY 
- EVEN 7;WORD ALIGNS CSI CONTROL BLOCK 
CSIBLK: .BLKB C.SIZE 7;NAMES CSI CONTROL BLOCK AND 


;ALLOCATES REQUIRED STORAGE 


The CSI$ macro does not generate any executable code. The CSI control block resulting from the 
.BLKB directive allows communication between CSI and the calling program. The symbol C.SIZE 
specifies the length of the control block. C.SIZE is defined during the expansion of the CSI$ macro. 
Expanding this macro also causes a local definition of the symbolic offsets and bit values within 
the CSI control block. 


You can cause the control block offsets to be defined globally within the current module. This is 
done by specifying DEF$G as an argument in the CSI$ initialization macro call, as follows: 


csI$s DEFSG 


CSI$ Macro Control Block Offset and Bit Value Definitions 


The CSI$ macro locally defines the symbolic offsets and bit values shown in Table 6-2 within the 
CSI control block. 


Table 6-2 CSI$ Offsets and Bit Values 


Symbolic 

Offset 

Name Description 

C.TYPR Command string request type 
This byte field indicates which type of file specification is being requested. Depending on whether 
an input or output file specification is being requested (see the io parameter in the CSI$2 macro cal 
described in Section 6.2.3.2), the corresponding bit in this byte is set. The bit definitions for this byte 
are as follows: 
CS.INP—Indicates that an input file specification is being requested. 
CS.OUT—Indicates that an output file specification is being requested. 

C.STAT Command string request status 


This byte field reflects the status of the current command line request. The bits in this field are 
initialized according to the following bit definitions: 


CS.EQU—Indicates that an equal sign (=) has been detected in the current command line, 
signifying that the command line contains both output and input file specifications. Once CS.EQU is 
set, CSI1 and CSI2 processing preserves the value of CS.EQU. 
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Table 6-2 (Cont.) CSI$ Offsets and Bit Values 


Symbolic 
Offset 
Name 


C.CMLD 


C.DSDS 


Description 


CS.NMF—Indicates that the current file specification contains a filename string. Accordingly, control 
block offset locations C.FILD+2 and C.FILD (see the entry for C.FILD) are initialized with the 
address and the length (in bytes), respectively, of the command line segment that contains the 
filename string. If no filename string is present, this bit is not set, and the filename string descriptors 
in the control block are cleared. 


(CS.DIF—Indicates that the current file specification contains a directory string. Thus, control block 
offset locations C.DIRD+2 and C.DIRD (see the description following for C.DIRD) are initialized with 
the address and the length (in bytes), respectively, of the command line segment that contains the 
directory string. If no directory string is present, this bit is not set. In this case, any residual nonzero 
values in the directory string descriptor cells that pertain to a previous command string request of 
similar type are used by default (see the description of C.TYPR). Thus, FCS uses the last directory 
string encountered in a file specification. 


CS.DVF—Indicates that the current file specification contains a device name string. Similarly, control 
block offset locations C.DEVD+2 and C.DEVD (see the description of C.DEVD) are initialized with 
the address and the length (in bytes), respectively, of the device name string. If no device name 
string is present, this bit is not set. Like CS.DIF (see the previous description of CS.DIF), any 
residual nonzero values in the device name descriptor cells that pertain to a previous command 
string request of similar type are used by default. Thus, the last device name string encountered in 
a file specification is used. 


2S.WLD—Indicates that the current file specification contains an asterisk (*), which signals the 
presence of a wildcard specification. 


CS.MOR—Indicates that the current file specification is terminated by a comma (,), which indicates 
that more file specifications are to follow. If this bit is not set, it signifies that the end of the input or 
output file specification has been reached. 


>ommand line descriptor 


This 2-word field is initialized with the length (in bytes) and the address, respectively, of the 
compressed command line. In other words, the values returned to these cells are the CSI output 
after it scans a file specification and removes all nonsignificant characters from the string (that is, 
nulls, unquoted blanks and tabs, and RUBOUTSs). 


CSI uses the values contained in these cells as the descriptors of the compressed command line to 
be parsed (see CSI$2 macro call in Section 6.2.3.2). 


Data-set descriptor pointer 


This pointer defines the address of the 6-word data-set descriptor in the CSI control block. This 
structure is functionally identical to the manually created data-set descriptor detailed in Chapter 2. 


You can use this symbol to initialize offset location F.DSPT in the FDB associated with the file to be 
processed. Thus, FCS is able to retrieve the American Standard Code for Information Interchange 
(ASCII) information from this structure that it needs to open files. 


Assembly-time initialization of FIDSPT in the associated FDB may be accomplished as follows: 


FDOPSA 1,CSIBLK+C.DSDS 


In this example, CSIBLK is the address of the CSI control block and C.DSDS represents the 
beginning address of the descriptor strings in the CSI control block (see the following entries for 
offset names) identifying the requisite ASCII file name information. 
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Table 6-2 (Cont.) CSI$ Offsets and Bit Values 


Symbolic 

Offset 

Name Description 
Runtime initialization of F.DSPT in the associated FDB may also be accomplished by using the dspt 
parameter of the FDOP$R macro call (see Chapter 2) or the generalized OPEN$x macro call (see 
Chapter 3). 

C.DEVD Device name string descriptor 
This 2-word field contains the address (C.DEVD+2) and the length in bytes (C.DEVD) of the most 
recent device name string (of those with the same request type) encountered in a file specification. 
Note that the colon that follows the device name is not included in the device name string. 

C.DIRD Directory string descriptor 
This 2-word field contains the address (C.DIRD+2) and the length in bytes (C.DIRD) of the most 
recent directory string (of those with the same request type) encountered in a file specification. Note 
that the brackets are included as part of the directory string 

C.FILD Filename String Descriptor 


This 2-word field contains the address (C.FILD+2) and the length in bytes (C.FILD) of the filename 
string in the current file specification. 


If an error condition is detected by the command syntax analyzer during the syntactical analysis of 
a command line (see Section 6.2.3.1), a segment descriptor is returned to this field, defining the 
address and the length of the command line segment in error. 


C.SWAD Current switch table address 


This word location contains the address of the switch descriptor table specified in the current CSI$2 
macro call (see Section 6.2.3.2). 


C.MKW1 CSI mask word 1 


This word indicates the particular switches present in the current file specification after each 
invocation of the CSI$2 macro call. The switch mask for each of the defined switches encountered 
in a file specification between delimiting commas is inserted into this location by a logical OR 
operation. This word is reset with each call to CSI$2 


The mask for a switch is specified in the CSISSW macro call (see Section 6.2.4.1). When a switch 
is encountered in a file specification for which a defined mask exists, the corresponding bits in 
C.MKW1 are set. By testing C.MKW1, you can determine the particular combination of defined 
switches present in the current file specification. 


C.MKW2 CSI mask word 2 
This word provides you with an indication of switch polarity. 


When a switch is present in a file specification and you do not negate that switch, the defined mask 
for that switch is inserted into C.MKW2 by a logical OR operation in the same manner as described 
previously for C.MKW1. Conversely, when a switch is present in a file specifier and you do negate 
that switch, the corresponding bits in C.MKW2 are cleared. Thus, you can check the polarity of 
each switch that C.MKW1 indicates is present by examining the corresponding bits in C.MKW2. 
This word is reset with each call to CSI$2 


C.SIZE Control block size indicator 
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Table 6-2 (Cont.) CSI$ Offsets and Bit Values 


Symbolic 

Offset 

Name Description 
This symbol, which is defined during the expansion of the CSI$ macro, represents the size in bytes 
of the CSI control block. 

C.EXPS User task expansion buffer size 


This symbol is the constant for your task’s expansion buffer size (for logical name expansion). It is 
currently set to 4840. 


CSI Runtime Macros 
Three runtime macro calls in CSI invoke routines that perform the following functions: 


CSI$1 Initializes the CSI control block, analyzes the command line (normally contained in the GCML 
command line input buffer), removes nonsignificant characters from the line, and checks the line 
for syntactic validity. This macro also initializes certain cells in the CSI control block with the address 
and the length, respectively, of the validated and compressed command line. 

CSI$2 Parses a file specification in the validated and compressed command line into its component device 
name, directory, and filename strings, and processes any associated switches and accompanying 
switch values. In addition, certain cells in.the CSI control block are initialized with the appropriate 
string descriptors for subsequent use by FCS in opening the specified file. 


6.2.3.1 CSI$1—Command Syntax Analyzer 


The CSI$1 macro invokes a routine called the command syntax analyzer. This routine analyzes a 
command line, which is normally read into the GCML command line input buffer, and checks it for 
correct syntax. In addition, it compresses the file specifications in the command line by removing 
all nonsignificant characters (that is, null, RUBOUT, and unquoted tabs and blanks). Finally, the 
command syntax analyzer initializes offset locations C.-CMLD+2 and C.CMLD in the CSI control 
block (see Section 6.2.2) with the address and the length (in bytes), respectively, of the validated 
and compressed command line. Each file specification in the command line is then parsed into 

its component device name, directory, and filename strings during each successive time the CSI$2 
macro call is issued (see Section 6.2.3.2). 


CSI$1_ csibik, buff,ien 


Parameters 


csiblk 


Specifies the address of the CSI control block. If you do not specify this parameter, RO is assumed 
to contain the address of the CSI control block. 


buff 


Specifies the address of a command line input buffer. This parameter initializes CSI control block 
offset location C.CMLD+2, enabling CSI to retrieve the current command line from a command 
line input buffer. 
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If you do not specify this parameter, you must manually initialize CSI control block offset location 
C.CMLD+2 with the address of a command line input buffer before issuing the CSI$1 macro call. 
The following statement shows one way to manually initialize this location: 


MOV GCLBLK+G.CMLD+2, CSIBLK+C .CMLD+2 


len 

Specifies the length of the command line input buffer. Similarly, this parameter initializes CSI 
control block offset location C.CMLD, thus completing the 2-word descriptor that enables CSI to 
retrieve the current command line from the input buffer. 


As with the buff parameter described previously, if you do not specify this parameter, you must 
manually initialize CSI control block offset location C.CMLD with the length of the command 
line input buffer before issuing the CSI$1 macro call. The following statement shows one way to 
manually initialize this location: 


MOV GCLBLK+G.CMLD, CSIBLK+C.CMLD 


The combination of the buff and len parameters described previously enables CSI to analyze the 
current command line. Following the analysis of the command line, CSI updates offset location 
C.CMLD with the length of the validated and compressed command line. 


If a syntactical error is detected during the validation of the command line, the Carry bit in the 
Processor Status Word (PSW) is set, and offset locations C.FILD+2 and C.FILD in the CSI control 
block (see Section 6.2.2) are set to values that define the address and the length, respectively, of 
the command line segment in error. 


Examples of how the CSI$1 macro call may be used in a program follow. 


Examples 
CSI$1 #CSIBLK, #BUFF, #LEN 


Shows symbols that represent the address and the length of a command line to be analyzed (not 
necessarily the line contained in the GCML command line input buffer). 


CSI$1 RO, GCLBLK+G.CMLD+2, GCLBLK+G.CMLD 


Assumes that RO has been preset with the address of the CSI control block; the next two 
parameters are direct references to the command line descriptor words in the GCML control 
block. 


CSI$1 #CSIBLK 


Assumes that the required descriptor values are already present in offset locations C.CMLD+2 anc 
C.CMLD of the control block (CSIBLK) as the result of prior action. 


6.2.3.2 CSI$2—Command Semantic Parser Macro 


The CSI$2 macro invokes the command semantic parser. This routine uses the values in CSI 
control block offset locations C.CMLD+2 and C.CMLD as the address and the length, respectively, 
of the command line to be parsed. The routine then parses the referenced line into its component 
device name, directory, and filename strings. The equal sign in the command line indicates that 
the string that follows is an input file specification. In addition, 2-word descriptors for these 
strings are stored in a 6-word data-set descriptor in the CSI control block, beginning at offset 
location C.DSDS (see Section 6.2.2). This field is functionally equivalent to the data-set descriptor 
created manually in your program (see Chapter 2). 
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The parser also decodes any switches and associated switch values present in a file specification, 
provided that the address of the appropriate switch descriptor table has been specified in the CSI$2 
macro call (see the following text). The CSI switch definition macro calls are described in detail in 
Section 6.2.4. 


CSI$2__csibik,io,swtab 


Parameters 


csiblk 


Specifies the address of the CSI control block. If you do not specify this parameter, RO is assumed 
to contain the address of the CSI control block. 


lo 


Specifies a symbol that identifies the type of file specification to be parsed. You may specify either 
of the following two symbolic arguments in this parameter field: 


INPUT The next input file specification in the command line is to be parsed. 
OUTPUT The next output file specification in the command line is to be parsed. 


You must initialize offset location C.TYPR in the CSI control block (see Section 6.2.2), either 
manually or through the CSI$2 macro call, with the type of file specification being requested. If 
arguments other than the symbolic arguments defined previously are specified in the CSI$2 macro 
call, an .ERROR directive is generated during assembly that causes the error message “Incorrect 
request to .CSI2" to be printed in the assembly listing. This diagnostic message alerts you to the 
presence of an invalid io parameter in the CSI$2 macro call. 


swtab 

Specifies the address of the associated switch descriptor table. You specify this optional parameter 
only if you suspect that the file specification contains a switch to be decoded. For you to specify 
this parameter, the program must already contain a switch descriptor table, which you created 
with the CSI$SW macro (see Section 6.2.4.1). In addition, if the switch to be decoded has any 
associated switch values, the program must already contain an associated switch value descriptor 
table, which you create with the CSI$SV macro call (see Section 6.2.4.2). 


This parameter initializes offset location C.SWAD in the CSI control block (see Section 6.2.2). If 
you do not specify this parameter, FCS uses any residual nonzero value in this cell by default as 
the switch descriptor table address. 


You can also initialize offset location C.SWAD manually prior to issuing the CSI$2 macro call, as 
shown in the following statement: 


MOV #SWTAB, CSIBLK+C.SWAD 


SWTAB is the symbolic address of the associated switch descriptor table. (The switch table must 
be aligned on an even address. ) 


If an error condition occurs during the parsing of the file specification, the Carry bit in the PSW is 
set, and control is returned to the calling program. The possible error conditions that may occur 
during command line parsing include the following: 


¢ The request type is invalid; that is, offset location C.TYPR in the CSI control block (see 
; Section 6.2.2) is incorrectly initialized. 


¢ The file specification contains a switch, but the address of the switch descriptor table is 
not specified in the CSI$2 macro call, or the switch descriptor table does not contain a 
corresponding entry for the switch. 


¢ §6The file specification contains an invalid switch value. 
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¢ The number of values accompanying a given switch in the file specification is greater than the 
number of corresponding entries in the switch value descriptor table for decoding those values. 


¢ The file specification contains a negative switch, but the corresponding entry in the switch 
descriptor table prevents you from negating the switch (see the nflag parameter of the CSI$SW 
macro call in Section 6.2.4.1). 


Examples of how the CSI$2 macro may be used in a program follow. 

Examples 
CSI$2  #CSIBLK, INPUT, #SWTBL 

Shows a request to parse an input file specification, which may include an associated switch. 
CSI$2 RO, OUTPUT, #SWTBL 


Assumes that RO presently contains the address of the CSI control block and parses an output file 
specification, which also may include a switch. 


CSI$2 #CSIBLK, INPUT 


Requests to parse an input file specification and to disallow any accompanying switches. 


CSI Switch Definition Macros 


The following macro calls create the requisite switch descriptor tables in your program for 
processing switches that appear in a file specification: 


CSI$SW Creates an entry in the switch descriptor table for a particular switch that you expect to encounter i 
a file specification. 

CSI$SV Creates a matching entry in the switch value descriptor table for the switch defined through the 
CSI$SW macro. 

CSI$SND Terminates a switch descriptor table or a switch value descriptor table created through the CSIfSW 


or the CSI$SV macro call, respectively. 


These macro calls are described in the following sections. 


6.2.4.1 CSI$SW—Create Switch Descriptor Table Entry Macro 


You must define a matching entry in the switch descriptor table for each switch that you expect 
your task to encounter in a file specification. If no switch descriptor table is specified or no 
corresponding entry exists, the presence of a switch in the command line causes an error. When 
your task issues a CSI$2 macro (see Section 6.2.3.2) and the address of a switch descriptor table i 
specified, the following processing occurs: 


1 For each switch encountered in a file specification, CSI searches the switch descriptor table fo 
a matching entry. If either the switch descriptor table address is not specified, or a matching 
switch entry is not found in the table, that switch is considered invalid. As a result, the Carr 

bit in the PSW is set, any remaining switches in the file specification are bypassed, and contri 
is returned to the calling program. 


2 Ifa matching entry is found in the switch descriptor table, mask word 1 in the CSI control 
block is set according to the defined mask for that switch (see C.MKW1, Section 6.2.2). 
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3 The negation status of the switch is determined. If you do not negate the switch, the 
corresponding bits in mask word 2 (C.MKW2) in the CSI control block are set according to 
_ the defined mask for that switch. If you negate the switch but negation is not allowed, the 
switch is considered invalid. In this case, the error sequence described in step 1 would occur. 
However, if you negate the switch, and negation is allowed, the corresponding bits in C.MKW2 
are cleared. 


The negation flag for a switch is established through the nflag parameter of the CSI$SW macro 
(described in the following text). 


4 Ifthe optional mask word address is not present in the corresponding switch descriptor table 
entry, that is, if you did not specify the mkw parameter in the associated CSI$SW macro, 
switch processing continues with step 7. If, however, you did specify the optional mask word 
address, switch processing continues with step 5. 


5 If SET has been specified as the clear/set flag in the corresponding switch descriptor table 
entry, and the switch is not negated, then the corresponding bits in the optional mask word 
are set according to the defined mask for that switch. If, however, you negate the switch, the 
corresponding bits in the optional mask word are cleared. 


You specify the clear/set flag as the csflg parameter in the CSI$SW macro. 


6 If CLEAR has been specified as the clear/set flag in the corresponding switch descriptor table 
entry, and the switch is not negated, the corresponding bits in the optional mask word are 
cleared. Conversely, if you negate the switch, the corresponding bits in the optional mask word 
are set. 


7 If a switch value accompanies a switch in a file specification, File Control Services (FCS) 
uses the associated switch value descriptor table created through the CSI$SV macro call (see 
Section 6.2.4.2) to decode the value. The switch value descriptor table must have at least as 
many entries as there are such values accompanying the switch in the file specification. If the 
switch value descriptor table is incomplete, or an invalid switch value is encountered, or the 
address of the switch value descriptor table is not present in the associated switch descriptor 
table, the switch is invalid, and the error sequence described in step 1 would occur. 


You specify the address of the switch value descriptor table as the vtab parameter in the 
CSI$SW macro call. 


label: CSISSW = sw,mk,mkw,csfig, nflg, viab,compfig 


Parameters 


label 

Specifies an optional symbol that names the resulting switch descriptor table entry and defines 
its address. To establish the address of a switch descriptor table, the first CSI$SW macro call 
issued in the program must include a label. This label allows the table to be referenced by other 
instructions in the program. 


SW 

Specifies the switch name to be stored as an entry in the switch descriptor table. This name may 
comprise any number of alphabetic characters. CSI compares the name entered on the command 
line with this switch name as entered in the switch descriptor table. This is a required parameter; 
if you omit it, the assembler generates an .ERROR directive during assembly that causes the error 
message “Missing switch name” to be printed in the assembly listing. 
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mk 

Specifies a mask that you define for the switch specified through the sw parameter. To enable CSI 
to indicate the presence of a given switch in a file specification, you must define a mask value for 
the switch, as follows: 


ASMSK = 1 
NUMSK = 2 
VWMSK = 40000 
XYMSK = 100000 


The octal value that you assign to each symbol defines a unique bit configuration. This 
configuration is to be set in CSI mask word 1 (C.MKW1) of the control block when a defined 
switch is encountered in a file specification. 


When you specify the appropriate symbol as the mk parameter in the CSI$SW macro call, 

the corresponding mask value is stored in the resulting switch descriptor table entry. Thus, a 
mechanism is established through which you can determine the particular combination of switches 
present in a file specification. For every matching entry found in the switch descriptor table, the 
corresponding bits are set in C.MKWI1. 


mkw 


Specifies the address in your program storage of a mask word that CSI changes each time it 
changes C.MKW1. CSI stores the same value into this mask word that it stores into C MKW1. 
This mask word can be manipulated, that is, changed or tested by the SET and CLEAR functions 
or by instructions in your program. You set the SET and CLEAR functions by using the csflg 
parameter. 


Such an optional word may be reserved through a statement logically equivalent to the following: 


MASKX: .WORD 0 


csfig 


Specifies a symbolic argument that specifies the clear/set flag for a given switch. This parameter 
is optional; if you do not specify it, SET is assumed. You may specify either one of two symbolic 
arguments for this parameter, as follows: 


CLEAR Indicates that the bits in the optional mask word corresponding to the switch mask are to be cleared, 
provided that you did not negate the switch. (If you negate the switch, the bits are set.) 


SET Indicates, conversely, that the bits in the optional mask word in your task corresponding to the switch 
mask are to be set, provided that you did not negate the switch. (If you negate the switch, the bits are 
cleared.) 


If you specify other than SET or CLEAR, the assembler generates a .ERROR directive that causes 
the error message “Invalid set/clear spec” to be printed in the assembly listing. 


nflg 


Specifies an optional negation flag for the switch. If you specify this parameter, it indicates that 
the switch can be negated, for example, /-LI or /NOLI. 


If you specify this parameter as other than NEG, the assembler generates an .ERROR directive 
that causes the error message “Invalid negate spec” to be printed in the assembly listing. If you dc 
not specify this parameter, the assumption is that switch negation is not allowed. 
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vtab 

Specifies the address of the switch value descriptor table associated with this switch. If you specify 
this optional parameter, it allows CSI to decode any switch values accompanying the switch, 
provided that you have defined an associated switch value descriptor table entry for that switch. 
The CSI$SV macro defines the switch value descriptor table. (If you specify the vtab parameter in 
the CSI$SV macro, you need not specify it in the CSI$SW macro call.) 


compfig 
Defines the method CSI uses to compare the switch name entered on the command line with the 
value entered in the switch descriptor table by the sw parameter. Either LONG or EXACT may be 
specified. The default value is entered if you do not specify a value. 


Following is a description of each value: 


Default if you do not code the parameter, only the first two characters of the switch name (specified by sw) 
are entered into the switch descriptor table and only these two characters are compared when the 
command line is parsed. Additional characters in the command line switch name are ignored. 


LONG All characters specified by the sw parameter are entered in the switch descriptor table. During compare 
processing, the first characters of the switch name on the command line must exactly match the value 
for the switch in the switch descriptor table. Additional characters in the command line switch name are 
ignored. 

EXACT All characters specified by the sw parameter are entered in the switch descriptor table. During compare 
processing, all the characters of the switch name on the command line must exactly match the value in 
the switch descriptor table. Extra characters in either the command line or the table are treated as an 
error. 


The switch table must be aligned on an even address. The format of the switch descriptor table 
entry created by the CSI$SW macro is shown in Figure 6-2. 


The switch name characters precede the control information in the table. The sign bit of each word 
indicates whether the following word contains more switch name characters. A sign bit set to 1 
indicates that the next word contains more switch name characters; whereas, a sign bit set to 0 
indicates that this is the last word containing switch name characters. 


If the number of characters in the switch name is odd, the high-order byte of the last word contains 
zeros, and CSI ignores it. 


The sign bit of the first byte of the last word of the switch name is the EXACT match bit. If this 
bit is set to 1, additional characters in the switch name on the command line are treated as an 
error by CSI; if this bit is set to 0, additional characters are ignored. 


The switch name characters are followed by entry control information consisting of the CSI mask 
word, the address of the area task of a mask word corresponding to the CSI mask word, and the 
address of the switch value table. 


A bit setting of 1 in the low-order bit of the address of your mask word indicates the CLEAR 
function; a bit setting of 0 indicates the SET function. 


The last word of the switch descriptor table entry contains the address of the switch value table. A 
bit setting of 1 in the low-order bit of this word indicates that the switch may be negated. 
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Figure 6-2 Format of Switch Descriptor Table Entry 


15 


| 0 
char2 char1 


lastchar EX nextlast 
Mask Word for this Switch 


Address of Optional User Mask Word 


Address of Switch Value Descriptor Table 


Example 


ASSWT: CSISSW AS, ASMSK,MASKX, SET, ,ASVTBL 


CSI$SSW NU,NUMSK, MASKX, CLEAR, NEG, NUVTBL 
CSISND 7END OF SWITCH DESCRIPTOR TABLE. 


Shows a 2-word entry switch descriptor table created through successive CSI$SW macro calls. 


The first parameter in the first statement creates an entry in the switch descriptor table for the /Af 
switch. The second parameter is an equated symbol that defines the switch mask, and the third 
parameter (MASKX) is the address of an optional mask word in your task (see the description of 
the mkw parameter). The fourth parameter indicates that the bits in MASKX that correspond to 
the switch mask are to be set. The fifth parameter (the negation flag) is null. The last parameter 
is the address of the associated switch value descriptor table. 


The second statement creates a switch descriptor table entry for the /NU switch. In contrast to th 
first statement, the fourth parameter (CLEAR) indicates that the bits in the optional mask word 

(MASKX) in your task that correspond to the switch mask are to be cleared. The fifth parameter 
(NEG) allows the switch to be negated, and the last parameter is the address of the switch value 
descriptor table associated with this switch. 


Note that the switch descriptor table entry macros are terminated with the CSI$ND macro (see 
Section 6.2.4.3). 
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6.2.4.2 CSI$SV—Create Switch Value Descriptor Table Entry Macro 


CSI$SV defines a switch value descriptor table entry. For every switch value that you expect your 
task to find with a given switch in a file specification, a corresponding switch value descriptor 
table entry must be defined in your program so that the switch value can be decoded. This macro 
creates a 2-word entry in the switch value descriptor table. The format of this table is shown in 
Figure 6-3. 


CSI$SV_type,adr,len 


Parameters 


type 
Specifies the conversion type for the switch value. Any one of four symbolic values may be 
specified. The possible conversion types include the following: 


ASCIl Indicates that the switch value is to be treated as an ASCII string. If you quote the string, the 
quotes are returned in the buffer as part of the string. If a quote appears anywhere in the switch 
value, all characters following it, up to the end of the line or another quote, are included in the 


string. 

NUMERIC Indicates a numeric switch value is to be converted to binary, using octal as a default conversion 
radix. 

OCTAL Indicates a numeric switch value is to be converted to binary, using octal as a default conversion 
radix. 

DECIMAL Indicates a numeric switch value is to be converted to binary, using decimal as a default 


conversion radix. 


If any parameter is specified other than these, a ERROR directive is generated during assembly 
that causes the error message “Invalid conversion type” to be printed in the assembly listing. If 
you do not specify any of the previously described parameters, ASCII is assumed by default. 


adr 

Specifies the address of your program location that is to receive the resultant switch value at the 
conclusion of switch processing. This parameter is required; if not specified, a ERROR directive is 
generated during assembly that causes the error message “Value address missing” to be printed in 
the assembly listing. 


len 

Specifies a numeric value that defines the length (in bytes) of the area that is to receive the switch 
value that results from switch processing. This parameter is also required; if not specified, a 
.ERROR directive is generated during assembly that causes the error message “Length Missing” to 
be printed in the assembly listing. 


The format of a switch value descriptor table entry created by a CSI$SV macro is shown in 
Figure 6-3. 


The low-order byte of the first word in the switch value descriptor table indicates whether the 
conversion type is ASCII or numeric. The low-order byte of this word is set to 1 if ASCII is 
specified; it is set to 2 if NUMERIC or OCTAL is specified; and it is set to 3 if DECIMAL is 
specified. The high-order byte of this word indicates the maximum allowable length (in bytes) of 
the switch value. 
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If the conversion type is ASCII, the len parameter reflects the maximum number of ASCII 
characters that can be deposited in the area defined through the adr parameter. The high-order 
byte of the first word in the switch value table then reflects the maximum length of the ASCII 
string. If the number of characters in the switch value exceeds the specified length, the extra 
characters are ignored. If, however, the actual number of ASCII characters present in the switch 
value falls short of the specified length, the remaining portion of the area receiving the resultant 
value is padded with nulls. 


If the conversion type is numeric, the length of the resulting binary value is either 2 bytes or 4 
bytes. If the size field is less than 4 bytes, 2 bytes are stored. If the size field is greater than 4 
bytes, 4 bytes are stored. You must align the buffer on a word boundary. 


If you specify the default conversion type for a switch value on numeric conversions, you can 
override it with a number sign (#) or a period (.). Preceding a numeric value with a number sign 
(for example, #10) forces the conversion type to octal; a numeric value followed by a period (for 
example, 10.) forces the conversion type to decimal. Note also that you may precede a numeric 
switch value with a plus sign (+) or a minus sign (—). The plus sign is the default assumption. 
If you specify an explicit octal switch value by using the number sign (#), the arithmetic sign 
indicator (+ or —), if included, must precede the number sign (for example, —#10). 


If the conversion type is decimal, the switch value is evaluated as a single number; an overflow 
into the high-order bit (bit 15) causes an error condition. However, if the conversion type is octal, « 
full 16-bit value may be specified. . 


Figure 6-3 Format of Switch Value Descriptor Table Entry 


16 0 


Switch Value Length Conversion Type 
Address of Location Receiving Switch Result 


Examples of how the CSI$SV macro call may appear in a program follow. 


Examples 
ASVTBL: CSI$SV ASCII,ASVAL, 3 
CSISSV ASCII, ASVAL+4, 3 
CSISND ;END OF SWITCH VALUE TABLE 
NUVTBL: CSISSV OCTAL,NUVAL, 2 


CSISSV DECIMAL, NUVAL+2, 2 
CSISND 7END OF SWITCH VALUE TABLE 


In these examples, the first parameter in the CSI$SV macro defines the conversion type. The nex 
two parameters, in all cases, define the address and the length of the program location that is to 
receive the resultant switch value. 
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You may reserve the required storage for the first switch value table ASVTBL: as follows: 
ASVAL: .BLKW 4 ;ASCII VALUE STORAGE 


You can similarly reserve the required storage for the second switch value table NUVAL: through 
the following statement: 


NUVAL: .BLKW 2 ;NUMERIC VALUE STORAGE 
Note again that switch value tables are terminated with the CSI$ND macro call. 


6.2.4.3 CSISND—Define End of Descriptor Table 


CSI$ND terminates descriptor tables with a 1-word entry. Switch descriptor tables and switch 
value descriptor tables must be terminated with a 1-word end-of-table entry. You can create this 
word, which contains 0, with the CSI$ND macro call. 


This macro call takes no arguments. The examples in 6.2.4.1 and 6.2.4.2 illustrate the use of this 
macro call. 
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7.1.1 


The Table-Driven Parser (TPARS) 


This chapter describes the table-driven parser (TPARS), which parses command lines. TPARS 
permits you to define and parse command lines in a unique syntax by using TPARS-supplied 
macros, built-in variables, and your own code. 


‘TPARS parses command lines according to syntax and semantics or meaning. The command line 


is made up of syntax elements. TPARS evaluates each syntax element of the command line based 
on a predefined arrangement of those elements. TPARS parses command lines by referencing a 
table that you define. You can build a state table, which contains states and transitions, by using 
the TPARS STATE$ and TRAN$ macros. A state delimits and represents a single syntax element 
on a command line. A transition is a statement that defines the processing required for parsing a 
given syntax element and contains instructions for further parsing at another state. TPARS uses 
subexpressions to resolve complex syntax elements. On the semantic level, TPARS also resolves 
the semantics or meaning of each element based on definitions supplied within action routines 
of your program. These action routines use TPARS macros, built-in variables, and your code to 
permit you to define and parse command lines. 


The parser routine that you write is included in your programs that parse command lines. 
TPARS is invoked from within an executing program by means of a CALL instruction. The 
CALL invokes the parser routine as well as the TPARS processor. For further information on 
the interrelationships among the calling program, the user-defined parser routine, and the TPARS 
processor, refer to Section 7.5. 


Coding TPARS Source Programs 


This section describes the three TPARS macros required to initialize and define the state table. 
Also included in this section is information describing action routines, TPARS built-in variables, 
and TPARS subexpressions. 


TPARS Macros—ISTAT$, STATE$, and TRAN$ 


TPARS provides macros that enable you to write a state table for parsing a unique command line. 
The ISTAT$ macro initializes a state table, the STATE$ macro defines a state (a particular syntax 
element) in your state table, and the TRAN$ macro defines the conditions for transition to another 
state. 

7.1.1.1 ISTAT$ Macro—lInitialize the State Table 
ISTAT$ initializes the state table. The state table is built using two macros: STATE$ and TRAN$, 
which are described in sections 7.1.1.2 and 7.1.1.3, respectively. This state table is built into a 
program section. Keyword strings that you define for parsing command lines are also accumulated 
in a program section. A third program section is also provided for a keyword pointer table used to 
enter the list of keyword strings. The ISTAT$ macro initializes these program sections. 


A blank STATE$ macro must follow the TPARS state table. 
ISTAT$  statetable,keytable, DEBUG 
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Parameters 


Sstatetable 
Specifies the label that you assign to the state table. TPARS recognizes this label as the start of 
the state table. 


keytable 
Specifies the label that you assign to the keyword table. TPARS recognizes this label as the start 
of the keyword table. 


$DEBUG 

Directs the assembler to list addresses of the state transition table in the assembly listing. These 
addresses are useful for tracing TPARS operation, using a debug routine that you supply (see 
Section 7.1.2.4). When you do not include $DEBUG, state transition table addresses are not listed. 


The state table is built in a program section named $STATE, the keyword strings are accumulated 
in a program section named $KSTR, and the keyword pointer table is built in a program section 
named $KTAB. 


If you define the symbol $RONLY, each of these program sections is generated as read-only. You 
generate a read-only state table by specifying the symbol $RONLY before the ISTAT$ macro in the 
following form: 


SRONLY = 1 
ISTATS$ statetable, keytable, $SDEBUG 


STATES 


7.1.1.2 STATES Macro—Defining a Syntax Element 


STATE$ declares the beginning of a state. This macro delimits one command line syntax element 
from another. A blank STATE$ macro must follow the TPARS state table. 


STATES [label] 


Parameter 


label 
Specifies an alphanumeric symbol that defines the address of the state. 


Each state defined by a STATE$ macro consists of any number of transitions defined by TRAN$ 
macros. The TRAN$ macros parse each syntax element. 


7.1.1.3 TRANS$ Macro—Defining a Transition 
The TRAN$ macro enables you to match each syntax element in a command line to a given type, 
to supply a symbolic address to the next TRAN$ macro, to supply an address of an action routine 
that might be required to process the syntax element further and to supply a mask that you can 
use as a flag in the parsing process. 


TRANS type { poate \ action mask][, maskaddr] 
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Parameters 


type 
Specifies the type of command line syntax element being parsed. You code the type parameter by 
using one of the following types of command line elements: 


Element Type Description 


$ANY Matches any single character. 

$ALPHA Matches any single alphabetic character (A—Z). 

$DIGIT Matches any single digit (0-9). 

$LAMDA Matches an empty string. This transition is always successful. LAMDA transitions are 


useful for getting action routines called without passing any of the input string. 


$NUMBR Matches any number. A number consists of a string of digits; a concluding period is 
optional. Numbers not followed by a period are interpreted as octal. Numbers followed 
by a period are interpreted as decimal and the decimal point is included in the matching 
string. A number is terminated by any nonnumeric character. Values through 2°*32-1 are 
converted to 32-bit unsigned integers. 


$SDNUMB Matches a decimal number. The string of digits is interpreted as decimal. With the 
exception that the matched string does not include the trailing decimal point, TPARS 
treats $DNUMB the same way it treats $NUMBR. 


$STRNG Matches any alphanumeric character string. The string will not be null. 


$RAD50 Matches any legal Radix-50 string, that is, any string containing alphanumeric characters, 
or the period (.), or dollar sign ($) characters. If you require Radix-50 conversion, the 
action routine in your code must convert this number. 


$BLANK Matches a string of blank and/or tab characters. 


$SEOS Indicates the position of the end of an input string. Once TPARS has reached the end 
of the input string, $EOS is the equivalent of that position as many times as $EOS is 
encountered in the state table. 


char Matches a single character in the syntax element whose American Standard Code for 
Information Interchange (ASCII) code corresponds to the value of char. The value of char 
must be a 7-bit ASCII code; that is, the value must be in the range 0-1773. Specify a single 
quote (") before char, such as ’A or ’X. 


“keyword” Matches a specified keyword. Keywords can be any length, can contain only alphanumeric 
characters, must be in uppercase, and are terminated by the first nonalphanumeric 
character encountered in parsing the keyword. The maximum number of keywords allowed 
in a state table is 64. 


label Matches the string processed by passing control to and executing the state table section 
that starts with a STATE$ macro that has the label parameter specified here as !label. 
In effect, this type of parameter passes control to a STATE$ macro subroutine or 
subexpression. For information on TPARS subexpressions, see Section 7.1.3. 


[label] 

([SEXIT] 

Specifies the label associated with a STATE$ macro to which execution control will pass after the 
code for this TRAN$ transition is executed. If the label parameter is omitted, execution control 


passes on to the next sequential STATE$ macro. A null label parameter is allowed only for the last 
transition in a state; a TRAN$ macro with a null label field must follow a TRAN$ macro. 


Specifying $EXIT in the label field terminates TPARS execution and returns control to the calling 
program. $EXIT also terminates a TPARS subexpression. 
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action 
Specifies the label of an action routine that you include in the parser routine of your code. This 
routine can include TPARS built-in variables, described in Section 7.1.2.1. 


mask 

Specifies a mask word to be stored in a location pointed to by the mask-word address whenever 
the TRAN$ macro is executed. If you specify mask, you must specify the maskaddr parameter as 
well (see the following parameter). This mask word is ORed into maskaddr when the transition is 
taken (after the action routine is called). 


maskaddr 
Specifies the label for an address into which TPARS stores the value specified by the mask 
parameter. You must specify the maskaddr parameter if you specify mask. 


The mask and maskaddr parameters provide a convenient means for flagging the execution of a 
particular transition. 


Action Routines and Built-In Variables 


Action routines process command line elements at the semantic level. That is, a given syntax 
element can have more than one meaning. Action routines determine and validate the meaning of 
the syntax elements. 


You write action routines in your parsing program to perform unique functions related to your 
program’s requirements. 


7.1.2.1 TPARS Bullt-in Variables 
TPARS provides the following built-in variables for action routines: 


.PSTCN Returns the character count of the portion of the input string matched by this transition. This 
character count is valid for all syntax types recognized by TPARS, including subexpressions. 


-PSTPT Returns the address of the portion of the input string matched by this transition. This address is 
valid for all syntactical types recognized by TPARS, including subexpressions. 


.PNUMH Returns the high-order binary value of the number returned by a $NUMBR or $DNUMB syntax type 
specification. 


-PNUMB Returns the low-order binary value of the number returned by a $NUMBR or $DNUMB syntax type 


specification. 
-PCHAR Returns the character found by the $ANY, $ALPHA, $DIGIT, or char syntax type specifications. 
.PFLAG Returns the value of the flag word passed to TPARS by register 1 (R1). Action routines can modify 
this word to change options dynamically. 
-TPDEB Contains the entry address of the optional debug routine that you write. 
R3 Returns the byte count of the remainder of the input string. When the action routine is called, the 


string does not include the characters matched by the current transition. 


R4 Returns the address of the remainder of the input string. When the action routine is called, the strin 
does not include the characters matched by the current transition. 


. 7.1.2.2 Calling Action Routines 
Action routines are called by a JSR PC (jump to subroutine program counter) instruction. Action 
routines can modify registers RO, R1, and R2; all other registers must be preserved. 
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7.1.2.3 Using Action Routines to Reject a Transition 
Action routines can reject a transition by returning to CALL+4 rather than to CALL+2. That is, 
the action routine performs the same function as an ADD #2,(SP) before returning to the caller. 
This technique enables additional processing of syntax types and extending of the syntax types 
beyond the set provided by TPARS. 


When an action routine rejects a transition, that transition has no effect. TPARS continues to 
attempt to match the remaining transitions in the state. 


7.1.2.4 Optional Debug Routine for |AS Users 


-A debug routine that you supply can be called by TPARS at each state transition, enabling the 


TPARS operation to be traced. For example, the routine can be written to display the contents 
of R5 each time the routine is called; R5 contains the current transition table address. You can 
monitor the TPARS operation by comparing the addresses displayed in the TPARS assembly 
listing, which shows the state transition table addresses. 


If a debug routine that you supply is to be called by TPARS, your task must first specify the entry 
point address for the debug routine in TPARS location .TPDEB, as follows: 


MOV #DENTER, .TPDEB 


Then, invoke TPARS with the .TPARD entry point (rather than with .TPARS). TPARS is invoked 
as described in Section 7.4. 


Upon entry to the debug program, central processing unit (CPU) registers contain the following: 
R3 Length of remainder of input string 


R4 Address of remainder of input string 
R5 Current address of transition table 


The debug routine must save and restore all registers prior to returning to TPARS. 


For addresses displayed by the debug routine to be useful, you must obtain an assembly listing 
showing the addresses of the state transition tables. These addresses are listed by the assembler if 
the optional $DEBUG parameter is provided in the ISTAT$ macro call (see Section 7.1.1.1). 


TPARS Subexpressions 


A TPARS subexpression is a series of states and transitions analogous to a subroutine. In general, 
such a series of states and transitions is used more than once during the parsing process. 


Subexpressions begin with a STATE$ macro specifying the label of the subexpression. You follow 
this macro by the states and transitions that comprise the body of the subexpression. To terminate 
the subexpression, specify a TRAN$ macro with the $EXIT keyword specified in the label field. 
The general form of a subexpression is shown in the example that follows. 


In this example, control is directed to the subexpression by a TRAN$ macro that specifies a !label 
syntax element as the type parameter, as follows: 


TRANS !UIC,NEXT 


‘TPARS then directs control to the STATE$ macro with the label UIC, as follows: 
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STATES UIC 
TRANS ’[ 

STATES 

TRANS SNUMBR, , SETGN 


STATES 
TRANS <’,> 


STATES 
TRANS SNUMBR,, SETPN 


STATES 
TRANS '],SEXIT 


When the User Identification Code (UIC) subexpression completes processing, control passes to th 
state labeled NEXT. 


General Coding Considerations 


This section contains information on how to arrange syntax types in a state table and how to dire 
TPARS to ignore blanks and table characters in a command line, and it provides rules for enterin, 
special characters (commas and angle brackets). 


Suggested Arrangement of Syntax Types in a State Table 


The transitions in a state might represent several syntax types; a portion of a string being scanne 
often matches more than one syntax type. Therefore, the order in which you enter the types in 
the state table is critical. Transitions are always scanned in the order in which they are entered, 
and the first transition matching a string being scanned is the transition taken. Therefore, the 
following order is recommended for states containing more than one syntax type: 


char 
keyword 
$EOS 
$ALPHA 
$DIGIT 


Placement of !label transitions in a state depends on the types and positions of other syntax type: 
in the state, as well as on the syntax types in the starting state of the subexpression. 


Ignoring Blanks and Tabs in a Command Line 


Bit 0 of the low byte of register 1 (R1) controls processing of blanks and tab characters. If this 
bit is 1 when TPARS is invoked, blanks and tab characters are processed in the same way any 
other ASCII character is processed; they are treated as syntax elements that require validation b 
TPARS. If this bit is set to 0, blanks and tab characters are interpreted as delimiter characters; 
they are ignored as syntax elements. In neither case does TPARS modify the command line. 
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When blanks are being ignored, the $BLANK syntax type never matches an element on the 
command line. Also, when this option is in effect, values returned to the !label syntax type by 
.PSTCN or .PSTPT can contain blanks or tabs, even though none were requested. The examples 
that follow show how TPARS parses the following string: 


ABC DEF 
The parsing might occur with and without the blank-suppress option. 


In the following example, an extra state is required to parse the blank: 


STATES 
TRANS SSTRNG 
STATES 
TRANS SBLANK 
STATES 
TRANS SSTRNG 


When TPARS is directed to ignore blanks and tab characters, the same string can be parsed using 
only two states, as follows: 


STATES 
TRANS $STRNG 
STATES 
TRANS SSTRNG 


Entering Special Characters 


In char syntax elements, MACRO-11 interprets commas (,), semicolons (;), and angle brackets 
(<>) as special characters. The comma is interpreted as an argument separator and angle brackets 
are used to enclose special characters in parentheses. 


To include a comma or a semicolon in a char syntax element string, use angle brackets as follows: 
TRANS <’,> 


Angle brackets cannot be passed as string elements in macro arguments. If required in a “char” 
expression, they must be expressed symbolically. For example: 


LA = '< 
TRANS LA 


Recognition of Keywords 


When TPARS encounters a transition table entry that specifies a keyword, it first scans from 
the current point in the input string in search of a delimiter (nonalphanumeric) character. The 
characters between the current input point and the next delimiter are then assumed to be a 
possible keyword and are matched against the entries in the keyword table. For this reason, the 
following example will not work as expected: 


STATES 

TRANS "NO", STATE1, SETNEG 
TRANS SLAMDA,,SETPOS 
STATES STATE1 

TRANS "AA",... 

TRANS "BB",... 
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When TPARS encounters the keyword NO, it scans and attempts to match the string “NOAA” or 
“NOBB”. If exact matching is requested, neither the “NO” transition nor the “AA” transition will 
match. In addition, if keyword matching is limited to two characters, the “NO” transition will 
match but TPARS will skip past “NOAA” so that the “AA” transition can be taken. You can use the 
following example to achieve the desired operation: 


STATES 
TRANS !NONO, STATE1, SETNEG 
TRANS SLAMDA, , SETPOS 


STATES STATE 
TRANS "AA",... 
TRANS "BB",... 


STATES NONO 


TRANS 'N 
STATES 
TRANS 'O, SEXIT 


In this example, TPARS attempts to match the subexpression NONO to the “NO” prefix one 
character at a time. This attempt bypasses the keyword scanning of TPARS, enabling the input 
pointer to be left pointing at “AA” or “BB”. If NONO fails, the input pointer will not be changed 
and the scan can continue by looking for “AA” or “BB”. 


Program Sections Generated by TPARS Macros 


TPARS macros generate three program sections. Data for the STATE$ macro are stored in the 
program section $STATE; whereas, data for the TRAN$ macro are stored in program sections 
$KSTR and $KTAB. The program section $KTAB contains addresses for each of the entries of the 
keyword syntax type. $KSTR contains the keyword entries separated by character code 377s. 


Each state consists of its transition entries concatenated in the order in which you specify them. 
The state label, if specified, is equated to the address of the first transition in the state. Each 
transition consists of from one to six words, as follows: 


Type Extension 


Action Return Address 


Mask Word 


Mask—Word Address 


| Target State Label 


The type byte of the first word can contain the following values: 
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Type 

Byte Value 

$LAMDA 300 

$NUMBR 302 

$STRNG 304 

$BLANK 306 

$SUBXP 310 (Used in the label type.) 

$EOS 312 

$DNUMB 314 

$RAD50 316 

$ANY 320 

$ALPHA 322 

$DIGIT 324 

char ASCIl code for the specified character 
keyword 200-+n (See the explanation that follows.) 


The value of keyword is 200+n, where n is an index into the keyword table. The keyword table is 
an array of pointers to keyword strings, which are stored in the program section $KSTR. Keyword 
strings in $KSTR are separated from each other by 3773. 


Bits in the flags byte indicate whether parameters for the TRAN$ macro are specified as follows: 


Bit Meaning 


Type extension is specified. 
Action routine label is specified. 
Target state label is specified. 
Mask word is specified. 
Mask-word address is specified. 


N & © DMD ~ O 


Indicates last transition in the current state. 


Invoking TPARS 


You control execution of TPARS by using the calling conventions and options described in this 
section. You invoke TPARS from within an executing program by using the following instruction: 


CALL - TPARS 


When a debug routine that you specify traces a TPARS operation (see Section 7.1.2.4), a special 
entry point is called, as follows: 


CALL - TPARD 


When your task calls TPARS in this manner, TPARS calls the debug routine at each state 


' transition. If your task invokes TPARS by the .TPARS entry point, the debug routine entry 


point address in .TPDEB is cleared and the debug routine is not called. 
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Register Usage and Calling Conventions 


When TPARS is invoked, registers in the calling program must contain the following information: 


R1 Options word 

R2 Pointer to the keyword table 

R3 Length of the string to be parsed 

R4 Address of the string to be parsed 

RS Label of the starting state in the state table 


On return from TPARS processing, registers contain the following information: 
R3 Length of the unscanned portion of the string 

R4 Address of the unscanned portion of the string 

The values of all other registers are preserved. 


The Carry bit in the Processor Status Word (PSW) returns 0 for a successful parse; the Carry bit is 
set when TPARS finds a syntax error. 


For an example of a calling sequence for TPARS, refer to Section 7.6.1. 


Using the Options Word 


The low byte of the options word contains flag bits. The only flag bit defined is bit 0, which controls 
processing of blanks. If bit 0 is set to 1, blanks are interpreted as syntax elements. If bit 0 is set 
to 0, blanks are ignored as syntax elements but are still processed as delimiters. 


The high byte of the options word controls abbreviation of keywords. If the high byte is set to 
0, keywords being parsed must exactly match their corresponding entries in the state table. If 
the high byte is set to a number, keywords being parsed can be abbreviated to that number of 
characters. 


TPARS clears the Carry bit in the PSW when it completes processing successfully. This occurs 
when a transition is made to $EXIT that is not within a subexpression. 


If a syntax error occurs, TPARS sets the Carry bit in the PSW and terminates. 


A syntax error occurs when there are no syntax elements in the current state that match the 
portion of the string being scanned. Illegal type codes and errors in the state table can also cause 
a syntax error. 


TPARS processing requires that the addresses in the state table and the keyword tables be reliable 
bad addresses might cause program termination. 


The only syntax types that can match the end of the string are $£OS and $LAMDA. 


How to Generate a Parser Program Using TPARS 


Three processing steps generate a parser program using TPARS, as shown in Figure 7-1. The 
source program must contain .MCALL statements for three macros: ISTAT$, STATE$, and TRAN$ 
These three MCALL statements must precede the statements that comprise the state table and 
action routines. 
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Assembling the source module produces an object module composed of three program sections. 
The assembly listing showing the code produced by the state table macros is not straightforward. 
The binary output of the macros is delayed by one statement. Thus, if you enable the listing of 
macro-generated binary code during assembly of the code, the binary code appearing after a macro 
call is, in fact, the result of the preceding macro call. Error messages generated by macro calls 
are similarly delayed. This is the reason an additional STATE$ macro is required to terminate the 
state table. 


When the parser program is linked and is in task image form, it can be invoked from within your 
executing task, as shown in Figure 7-1. 


Figure 7-2 shows the CALL .TPARS statement that invokes the parser program and the TPARS 
processor. As the parser executes the state table, it calls action routines. These action routines 
access code in the TPARS processor to perform such functions as returning the values of the 
built-in variables. When the state table completes execution, TPARS receives control and passes 
control back to the calling program. 


Programming Examples 


This section includes three programming examples of how TPARS can be used in your program. 
The first example shows the code required to parse a User File Directory (UFD) command line for 
IAS. The second example shows the use of subexpressions and how to reject transitions. The third 
example shows how to use subexpressions to parse complex command lines. 


Parsing a UFD Command Line 


This example shows the code required to parse a UFD command line. It includes a state table and 
action routines. The general form of the UFD command line is as follows: 


UFD DUO: LABEL[201, 202] /ALLOC=100./PRO=[{RWED, RWED, RWE, R} 


The action routines in this parser program return the following values: 
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Figure 7-1 Processing Steps Required to Generate a Parser Program Using TPARS 


PARSER.SRC 


MCALL ISTAT$ 


_ .» that includes the MCALL TRANS 


EDI > 


required MCALL STATE$ 

statements. ; 
aes ; 
————-_ LSTATES$ 


MACRO-11 PARSER.OBJ 


2. Assemble the 


source program to ee 


produce an object 
module. 
PARSER.SRC — ; : 


$KSTR 


3. Execute the Task MYFILE.TSK 
Builder to produce ae 


a task image 
including the parser. 


L a 


The Table-Driven Parser (TPARS) 


Figure 7-2 Flow of Control When TPARS Is Called from an Executing User Program 


Executing User-Defined TPARS 
User Program Parser Program Processor 


CALL. TPARS 


Routines 
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Action Routine Value 


$UDEV Device name (two ASCII characters) 

$UUNIT Unit number (binary) 

SUVNML Byte count of the volume label string 

$UVNAM Address of the volume label string 

$UUIC Binary UIC for which to create a directory 

$UALL Number of directory entries to preallocate 

$UPRO Binary protection word for UFD 

$FLAGS Flags word containing the following bits: 
UF.ALL Set if allocation was specified. 
UF.PRO Set if protection was specified. 


The label and the /ALLOC and /PRO switches are optional. The calling sequence for this routine ik 
as follows: 

CLR Ri 

MOV #UFDKTB,R2 

MOV COUNT,R3 

MOV ADDR,R4 

MOV #START,R5 

CALL .TPARS 

BCS ERROR 


The following is an example of the parser routine that you write: 


-TITLE STATE TABLE FOR UFD COMMAND LINE 
-MCALL ISTATS,STATES, TRANS 

; TO BE USED WITH BLANK SUPPRESS OPTION 
ISTAT$ UFDSTB,UFDKTB 


7 READ OVER COMMAND NAME 
-GLOBL START 


STATES START 
TRANS "UFD" 
7 READ DEVICE AND UNIT NUMBER 


STATES 
TRANS SALPHA, , SETDV1 


STATES 
TRANS SALPHA, , SETDV2 


STATES 
TRANS  $NUMBR,DEV1,SETUNT 
TRANS  SLAMDA 


STATES DEV1 
TRANS ae 


7 READ VOLUME LABEL 


STATES 

TRANS 

TRANS 
READ UIC 


ve 


STATES 
TRANS 


ze 


STATES 
TRANS 
TRANS 


STATES 

TRANS 

TRANS 
SET ALLOCATION 


we 


STATES 
TRANS 


STATES 
TRANS 
PROTECTION 


™e 


STATES 
TRANS 


STATES 
TRANS 


STATES 
TRANS 
TRANS 
TRANS 
TRANS 
TRANS 
TRANS 
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$STRNG, RUIC, SETLAB 
SLAMDA 


RUIC 
!uIC 


SCAN FOR OPTIONS AND END OF LINE 


OPTS 


$EOS, SEXIT 
‘f/f 


"ALLOC", ALC, , UF .ALL, $FLAGS 


"PRO", PRO, , UF.PRO, SFLAGS 


’' [,,IGROUP 


SPRO 

'], OPTS, ENDGRP 
<',>, SPRO, NXGRP 
’R, SPRO, SETRP 
'W, SPRO, SETWP 
‘E, SPRO, SETEP 
'D, SPRO, SETDP 


7; SUBEXPRESSION TO READ AND STORE UIC 


STATES 
TRANS 


STATES 
TRANS 


STATES 
TRANS 


STATES 
TRANS 


STATES 
TRANS 


STATES 


KEYWORD TABLE SIZE: 
+ KEYWORD POINTER SPACE: 


“=e Se 


-SBTTL ACTION 

7 DEVICE NAME CHAR 1 

SETDV1: :MOVB - PCHAR, 
RETURN 


7; DEVICE NAME CHAR 2 


SETDV2: :MOVB -PCHAR, 


RETURN 


UIC 
| 


SNUMBR, , SETGN 


<',> 


$NUMBR, , SETPN 


'],SEXIT 


STATE TABLE SIZE: 60 WORDS 


8 WORDS 
3 WORDS 


ROUTINES FOR THE COMMAND LT™NE PARSER 


SUDEV 


SUDEV+1 
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7; UNIT NUMBER 


SETUNT: : MOV . PNUMB, SUUNIT 
RETURN 

; VOLUME LABEL 

SETLAB: :MOV -PSTCN, SUVNML 
MOV -PSTPT, SUVNAM 
RETURN 


7 PPN - GROUP NUMBER 


SETGN: : MOVB . PNUMB, SUUIC+1 
BR TSTPPN 
; PPN - PROGRAMMER NUMBER 
SETPN: : MOVB . PNUMB, SUUIC 
TSTPPN: TST . PNUMH ; CHECK FOR O HIGH ORDER 
BNE 10$ 
TSTB . PNUMB+1 ; CHECK FOR BYTE VALUE 
BEQ 208 
10$; ADD #2, (SP) ; BAD VALUE - REJECT TRANSITION 
20S; RETURN 
; NUMBER OF ENTRIES TO ALLOCATE 
SETALC: :MOV - PNUMB, SUALL 
RETURN 
; SET PERMISSIONS 
3; INITIALIZE 
IGROUP : :MOV #4,GRCNT 
; MOVE TO NEXT PERMISSIONS CATEGORY 
NXGRP:: SEC ; FORCE ONES 
ROR SUPRO 
ASR SUPRO ; SHIFT TO NEXT GROUP 
ASR SUPRO 
ASR SUPRO 
DEC GRCNT ; COUNT GROUPS 
BGE 308 ; TOO MANY IS AN ERROR 
BADGRP : ADD #2, (SP) ; IF SO, REJECT TRANSITION 
30S: RETURN 
; SET READ PERMIT 
SETRP:: BIC #FP .RDV*10000, SUPRO 
RETURN 


7; SET WRITE PERMIT 


SETWP:: BIC #FP .WRV*10000, SUPRO 
RETURN 


+ SET EXTEND PERMIT 


SETEP:: BIC #FP .EXT*10000, SUPRO 
RETURN 


7 SET DELETE PERMIT 


SETDP :: BIC #FP ..DEL*10000, SUPRO 
RETURN 

? END OF PROTECTION SPEC 

ENDGRP: : TST GRCNT ; CHECK THE GROUP COUNT 
BNE BADGRP ; MUST HAVE 4 
RETURN 
- END UFD 
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Using Subexpressions and Rejecting Transitions 


The following example is an excerpt from a state table that parses a string in which the first 
character is interpreted as a quote character. This typical construction occurs in many editors and 
programming languages. The action routines associated with the state table return the byte count 
and address of the string in the locations QSTC and QSTP. The quoting character is returned in 
location QCHAR. 


; MAIN LEVEL STATE TABLE 

7 

; PICK UP THE QUOTE CHARACTER 
STATES STRING 


TRANS SANY, , SETQ 
3; ACCEPT THE QUOTED STRING 


STATES 

TRANS !QSTRG, , SETST 
; GOBBLE UP THE TRAILING QUOTE CHARACTER 

STATES 


TRANS SANY, NEXT, RESET 
7; SUBEXPRESSION TO SCAN THE QUOTED STRING 
; THE FIRST TRANSITION WILL MATCH UNTIL IT IS REJECTED 
7; BY THE ACTION ROUTINE 


STATES QSTRG 

TRANS SANY, QSTRG, TESTQ 
TRANS $LAMDA, SEXIT 
STATES 


7; ACTION ROUTINES 


; STORE THE QUOTING CHARACTER 


SETQ: MOVB - PCHAR, QCHAR 
INCB - PFLAG 7 TURN OFF SPACE FLUSH 
RETURN 
7 TEST FOR QUOTING CHARACTER IN THE STRING 
TESTQ: CMPB - PCHAR, QCHAR 
BNE 10$ 
ADD #2, (SP) 7; REJECT TRANSITION ON MATCH 
108: RETURN 
; STORE THE STRING DESCRIPTOR 
SETST: MOV -PSTPT, QSTP 
MOV -PSTCN, QSTC 
RETURN 
; RESET THE SPACE FLUSH FLAG 
RESET: DECB - PFLAG 
RETURN 


Using Subexpressions to Parse Complex Command Lines 


The following excerpt from a state table shows how subexpressions are used to parse complex 
command lines. 


The state table accepts a number followed by a keyword qualifier. Depending on the keyword, the 


number is interpreted as either octal or decimal. The binary value of the number is returned in 
the tagged NUMBER. The following types of strings are accepted: 
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10/OCTAL 
359/DECIMAL 
77777/OCTAL 


; MAIN STATE TABLE ENTRY - ACCEPT THE EXPRESSION AND 
; STORE ITS VALUE 


STATES 
TRANS !ONUMB, NEXT, SETNUM 
TRANS !DNUMB, NEXT, SETNUM 

; SUBEXPRESSION TO ACCEPT OCTAL NUMBER 
STATES ONUMB 
TRANS SNUMBR 


STATES 
TRANS a 
STATES 
TRANS "OCTAL", SEXIT 
: SUBEXPRESSION TO ACCEPT DECIMAL NUMBER 
STATES DNUMB 
TRANS SDNUMB 


STATES 
TRANS ue 


STATES 
TRANS "DECIMAL", SEXIT 
STATES 
7 ACTION ROUTINE TO STORE THE NUMBER 
SETNUM: MOV - PNUMB, NUMBER 
MOV - PNUMH, NUMBER+2 
RETURN 


The contents of PNUMB and .PNUMH remain undisturbed by all state transitions orev the 
$NUMBR and $DNUMB types. 


Because of the way in which subexpressions are processed, calls to action routines from within 
subexpressions must be handled with care. 


When a subexpression is encountered in a transition, TPARS saves its current context and calls 
itself, using the label of the subexpression as the starting state. If the subexpression parses 
successfully and returns by means of $EXIT, the transition is taken and control passes to the next 
state. If the subexpression encounters a syntax error, TPARS restores the saved context and tries 
to take the next transition in the state. 


However, TPARS provides no means for resetting original values changed by action routines that 
were called by subexpressions. Therefore, action routines called from subexpressions should store 
results in an intermediate area. Data in this intermediate area can then be accessed by an action 
routine called from the primary level of the state table. 
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Spooling 


File Control Services (FCS) provides facilities at both the macro and subroutine level to queue 
files for subsequent printing. As a result, your task can queue a print job. Your task can spool to 
output for printing in several ways; however, you cannot control the printing from within your task 
as you can with the Digital Command Language (DCL) command PRINT. You can, however, use 
the DCL command SET QUEUE (Monitor Console Routine (MCR) command QUE /MOD) to alter 
the attributes of the print job once the job appears in the queue. 


PRINT$ Macro 


A task issues the PRINT$ macro to queue a file for printing on a specified device. The specified 
device must be a unit record, carriage-controlled device such as a line printer or terminal. The file 
is placed in the default queue PRINT. If the device is not specified, LP is used. 


The file to be spooled must be open when the PRINT$ macro is issued. Once the file is queued, 
PRINTS$ closes the file. Error returns differ from normal FCS conventions. Refer to Section 8.3 for 
more information. 


PRINTS fdb,err 


Parameters 


fdb 


Specifies the address of the associated File Descriptor Block (FDB). This parameter need not be 
present if the address of the associated FDB is already in RO. 


err 


Specifies the address of an optional, error-handling routine that you code. See Section 8.3 for more 
information. 


-PRINT Subroutine 


Your task can open a file on disk, send output to the disk, and close the file either by using 

the PRINT$ macro call or by calling the .PRINT subroutine to spool the output. The .PRINT 
subroutine is called to queue a file for printing. Before your task can call .PRINT, RO must contain 
the address of the associated FDB and the file must be open. Next, the file is placed in the default 
queue PRINT and the .PRINT routine closes the file. One copy of the file is printed on the LP 
device. In your task, it may be preferable to call the PRINT subroutine if the routine resides in 
FCSRES. Using the PRINT$ macro causes all the code of .PRINT to appear in your task each time 
it is used. 


Section 8.3 describes error handling for the .PRINT file control routine. 


8.2.1 


8.2.2 


8.3 


Spooling 


Opening a File on Disk and Using the PRINT Command 


As stated in the opening of this section, your task can open a file on disk, send output to that disk, 
and close the file. When the task exits, the PRINT command can print the file. This is the only 
method that gives you access to the PRINT command qualifier. 


If you run your task from an indirect command file or batch job that includes a PRINT command 
after the task exits, the difference between spooling from within a task or from outside it is 
negligible. 


Note that you can use the SPWN$ directive in the task to issue the PRINT command. (Refer to 
the IAS Executive Facilities Reference Manual.) 


Opening a File on LP 


Your task can use the OPEN$ macro to name the output device. FCS opens the file on pseudo 
device SP0:. The file is placed in the device-specific queue for the device you named. When your 
task has finished writing to this file, close it with a CLOSE$ macro. The file is deleted after it is 
printed. 


Error Handling 


The error returns provided with PRINT$ and .PRINT differ from the standard FCS error returns. 
Unlike FCS error returns, PRINT$ and .PRINT error codes are placed in FERR or in the Directive 
Status Word (DSW), depending on when the failure occurred. 


If the failure is FCS related (for example, the PRINT$ macro cannot close the file), the Carry bit is 
set and F.ERR contains the error code. If the failure is related to the SEND/REQUEST directive 
that queues the file, the Carry bit is set and the DSW contains an error code. DSW error codes are 
listed in the JAS Executive Facilities Reference Manual. 


Normally, once you determine that the Carry bit is set, any error routine that you code should first 
test F ERR and then test the DSW error code. 
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File Descriptor Block 


A File Descriptor Block (FDB) contains file information that is used by File Control Services (FCS) 
and the file control primitives. Figure A-1 and Figure A—2 display the layout of the FDB. 


Note that each section within the FDB contains symbolic offset names and each offset’s location. 
‘You can define an FDB offset name locally or globally. To define an offset locally, use either of the 
following macro calls: 


FDOFSL 7;DEFINE OFFSETS LOCALLY. 
FDOFF$ DEFSL 7;DEFINE OFFSETS LOCALLY. 


To define an FDB offset name globally, use the following macro call: 


FDOFF$ DEFSG ;DEFINE OFFSETS GLOBALLY. 


NOTE: When you refer to FDB locations, it is essential to use the symbolic offset names 
rather than the actual address of such locations. The position of information within the 
FDB may be subject to change from version to version; whereas, the offset names remain 
constant. 


Table A—1 describes the offset locations within the FDB. 
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Figure A-1_ File Descriptor Block Format 


File—Attribute Section 


0 F.RTYP 
2 F.RSIZ 
4 F.HIBK 
10 F.EFBK 
14 F.FFBY 
FRCTL 1 16 F.RACC 
Block I/O Buffer Descriptor 20 F.BKDS 
a 20 F.URBD 
24 F.NRBD 
Block I/O Status Block Address 24 F.BKST 
Block I/O Done AST Address 26 F.BKDN 
Override Block Buffer Size 30 F.OVBS 
Next Record Address in Block Buffer 30 F.NREC 
End—of-Block Buffer 32 F.EOBB 
2 Record | Number for Random Records _ oe 34 F.RCNM 
Size in Blocks of Contiguous File 34 F.CNTG 


Address to Read in Statistics Block 36 F.STBK 
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Figure A-2 File Descriptor Block Format (Continued) 


File-Open Section 


Amount of Space Allocated When Needed 40 F.ALOC 

F.FACC 43 File Access Logical Unit Number 42 F.LUN 
File Descriptor Pointer | 44 F.DSPT 
Default Filename Block Address 46 F.DFNB 


Block—Buffer Section 
F.BKP1 51 Bookkeeping Bits QIO Event Flag 50 F.EFN or F.BKEF 


53] 2d Byte Error Return Code}1st Byte Error Return Code] 52 F.ERR 
F.MBC1 56| Number of Buffers in Use| Number of Buffers Desired) 54 F.MBCT 


F.BGBC 57. Big Buffer Block Count (biks) Multiple Buffer Control Flags | 56 F.MBFG 
Virtual Block Size (Bytes) 
Block Buffer Size 
Block I/O Virtual Block Number 64 F.BKVB 
on Messe. _ Virtual Block Number — | 64 F.VBN 
Block Buffer Descriptor Block . 70 F.BDB 
FDB Extension Address 72 F.EXT 
F.CHR 75] cp volume Character Byte 74 F.FLG 
Access Control Word 76 G.ACTL 
Sequence Number for Sequenced Files 100 F.SEQN 
Beginning of Filename Block 102 F.FNB 
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Table A-1 


Symbolic 
Offset 
Name 


F.RTYP 


F.RATT 


F.RSIZ 


F.HIBK 
F.EFBK 


F.FFBY 


F.RACC 


FDB Offset Definitions 


Size 
(Bytes) 


1 


1 


Contents 


This byte is set, as follows, to indicate the type of records for the file: 


F.RTYP = 1 Indicates fixed-length records (R.FIX). 

F.RTYP =2 Indicates variable-length records (R.VAR). 

F.RTYP =3 Indicates sequenced records (R.SEQ). 

Bits 0 to 3 are set to indicate record attributes, as follows: 

Bit O = 1 Indicates that the first byte of a record is to contain a FORTRAN carriage 


control character (FD.FTN); otherwise, it is 0. 


Bit 1 = 1 Indicates, for a carriage control device, that a line feed is to be performed 
before the line is printed and a carriage return is to be performed after 
the line is printed (FD.CR); otherwise, it is 0. 


Bit 2 = 1 Indicates the “print file format” (FD.PRN). FCS allows this attribute but 
does not interpret the format word. 


Bit 3 = 1 indicates that records cannot cross block boundaries (FD.BLK); 
otherwise, it is 0. 


This location contains the size of fixed-length records or indicates the size of the largest 
record that currently exists in a file of variable-length records. 


Indicates the highest virtual block number allocated. 
Contains the end-of-file (EOF) block number. 
The format of the block number is high-order word followed by low-order word. 


Indicates the first free byte in the last block or the maximum block size for magnetic 
tape. 


Bits 0 to 3 of this byte define the record access modes, as follows: 


Bit O = 1 Indicates READ$/WRITES$ mode (FD.RWM); otherwise, it is 0 to indicate 
GET$/PUT$ mode. 

Bit 1 = 1 Indicates random access mode (FD.RAN) for GET$/PUT$ record I/O; 
otherwise, it is 0 to indicate sequential access mode. 

Bit 2 = 1 Indicates locate mode (FD.PLC) for GET$/PUT$ record I/O; otherwise, it 


is 0 to indicate move mode. 


Bit 3 = 1 Indicates that PUT$ operation in sequential mode does not truncate 
the file (FD.INS); otherwise, it is 0 to indicate that PUT$ operation in 
sequential mode truncates the file. 
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Table A-1 (Cont.) FDB Offset Definitions 


Symbolic 
Offset 
Name 


F.RCTL 


F.BKDS 
or 
F.URBD 


F.NRBD 


or 

F.BKST 
and 

F.BKDN 


F.LOVBS 
or 
F.NREC 
F.EOBB 
F.RCNM 


or 
F.CNTG 


and 


F.STBK 
F.ALOC 


F.LUN 


Size 
(Bytes) 


{ 


1 


Contents 


Bits 0 to 5 define the characteristics of the device associated with the file, as follows: 

Bit O = 1 Indicates a record-oriented device (FD.REC), for example, a 
teletypewriter or line printer; a value of 0 indicates a block-oriented 
device, for example, a disk or DECtape. 


Bit 1 = 1 Indicates a carriage control device (FD.CCL); otherwise, it is 0. 

Bit 2 = 1 Indicates a teleprinter device (FD.TTY); otherwise, it is 0. 

Bit 3 = 1 Indicates a directory device (FD.DIR); otherwise, it is 0. 

Bit 4 = 1 Indicates a single directory device (FD.SDI). A Master File Directory 


(MFD) is used, but no User File Directories (UFDs) are present. 


Bit 5 = 1 Indicates a block-oriented device that is inherently sequential in nature 
(FD.SQD), such as magnetic tape. A record-oriented device is assumed 
to be sequential in nature; therefore, this bit is not set for such devices. 


Contains the block I/O buffer descriptor. 


Contains the user record buffer descriptor. 


Contains the next record buffer descriptor. The record buffer descriptor contains the size 
of the buffer in the first word and the address of the buffer in the second word. 


Contains the address of the !/O status block (IOSB) for block 1/O. 


Contains the address of the asynchronous system trap (AST) service routine for block 
VO. 


This field has meaning only before the file is opened. 


Contains the address of the next record in the block. 
Contains a value defining the end-of-block buffer. 


Contains the number of the record for random access operations. The format of the 
record number is the high-order word followed by the low-order word. 


Contains a numeric value defining the number of blocks to be allocated in creating a 
new file. This cell has meaning only before the file is opened. A value of 0 means 
leave the file empty; a positive value means allocate the specified number of blocks as 
a contiguous area and make the file contiguous; a negative value means allocate the 
specified number of blocks as a noncontiguous area and make the file noncontiguous. 


Contains the address of the statistics block in your program. 


Contains the number of blocks to be allocated when the file must be extended. A 
positive (+) value indicates contiguous extend, and a negative (—) value indicates 
noncontiguous extend. 


Contains the logical unit number associated with the FDB. 
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Table A-1 (Cont.) FDB Offset Definitions 


Symbolic 
Offset Size 
Name (Bytes) Contents 
F.FACC 1 This byte indicates the access privileges for a file, as follows: 
Bit O = 1 If the file is accessed for reading only (FA.RD). 
Bit 1 = 1 If the file is accessed for writing (FA.WRT). 
Bit 2 = 1 If the file is accessed for extending (FA.EXT). 
Bit 3 = 1 If a new file is being created (FA.CRE); otherwise, i is 0 to indicate an 
existing file. 
Bit 4 = 1 If the file is a temporary file (FA. TMP). 
Bit 5 = 1 If the file is opened for shared access (FA.SHR). 
If Bit 3 equals 0, then the following is true: 
Bit6=1 If an existing file is being appended (FA.APD). 
If Bit 3 equals 1, then the following is true: 
Bit6=1 If not superseding an existing file at file-create time (FA.NSP). 
F.DSPT 2 Contains the data-set descriptor pointer. 
F.DFNB 2 Contains the default filename block pointer. 
F.BKEF 1 Contains the block I/O event flag. 
FEFN Contains the record I/O event flag. 
F.BKP1 1 Contains bookkeeping bits for FCS internal control. 
F.ERR 1 A negative value indicates an error condition. 
F.ERR+1 1 Used in conjunction with F.ERR. If F.ERR is negative, the following applies: 
F.ERR+1 = 0 Indicates that the error code is an 1/O error code (see 
error codes in Appendix K). 
F.ERR+1 = negative value Indicates that the error code is a Directive Status 
Word (DSW) error code (see DRERR$§ error codes in 
Appendix K). 
F.MBCT 1 Indicates the number of buffers to be used for multibuffering. 
F.MBC1 1 Indicates the actual number of buffers currently in use if the multibuffering version of 
FCS is in use. 
F.MBFG 1 Contains either one of the multibuffering flags, as follows: 
Bit 0 = 1 Indicates read-ahead (FD.RAH). 
Bit 1 = 1 Indicates write-behind (FD.WBH). 
F.BGBC 1 Indicates big-buffer block count in number of blocks if the big-buffer version of FCS is in 
use. 
Buffer offset for reading ANSI magnetic tape in record mode. 
F.VBSZ 2 Contains the virtual block size (in bytes). | 
F.BBFS 2 Indicates the block buffer size. 
F.BKVB 4 Contains the virtual block number in the user program for block I/O. 
or 
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Table A-1 (Cont.) FDB Offset Definitions 


Symbolic 
Offset Size 
Name (Bytes) Contents 
F.VBN Contains the virtual block number. The format of the virtual block number is the 
high-order word followed by the low-order word. 
F.BDB 2 Contains the address of the block buffer descriptor block. This location always contains 
a nonzero value if the file is open and a zero value if the file is closed. 
F.EXT 2 Address of FDB exterision. 
F.FLG 1 Flag byte. 
F.CHR 1 The control bit is defined as follows: 
Bit O = 1 Indicates ANSI magnetic tape formats D or F. 
F.ACTL 2 The low-order byte of this word indicates the number of retrieval pointers to be used for 
the file. The control bits are in the high-order byte and are defined as follows: 
Bit 15 = 1 Specifies that control information is to be taken from F.AACTL (FA.ENB). 
Bit 12 = 0 Causes positioning to the end of a magnetic tape volume set upon open 
or close. 
Bit 12 = 1 Causes positioning of a magnetic tape volume set to just past the most 
recently closed file when the next file is opened (FA.POS). 
Bit 11 = 1 Causes a magnetic tape volume set to be rewound upon open or close 
(FA.RWD). 
Bit 9 = 1 Causes a file to be unlocked if it is not properly closed when accessed 
for write (FA.DLK). 
F.SEQN 2 Contains the sequence number for sequenced records. 
F.FNB —_— The symbolic offset of the beginning of the filename block portion of the FOB. 


Filename Block 


A filename block is the portion of the File Descriptor Block (FDB) that contains the various 
elements of a file specification used by File Control Services (FCS). The format of a filename block 
is illustrated in Figure B—1. 


‘Figure B-1 Filename Block Format 
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Length in 
Bytes 
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Offset names in a filename block can be defined either locally or globally. You can define an offset 
name locally by using either of the following macro calls: 


NBOFSL ;DEFINE OFFSETS LOCALLY. 
NBOFFS DEFSL ;DEFINE OFFSETS LOCALLY. 


Filename Biock 


To define an offset name globally, use the following macro call: 


NBOFFS$ DEFSG ;DEFINE OFFSETS GLOBALLY. 


NOTE: When you refer to filename block locations, it is essential to use the symbolic 
offset names rather than the actual addresses of such locations. The position of 
information within the filename block might change from release to release, whereas 
the offset names remain constant. 


The offset names in a filename block are described in Table B—1. 


Table B-1 Filename Block Offset Definitions 


Symbolic 

Offset Size 

Name (Bytes) Contents 

N.FID 6 File identification field 

N.FNAM 6 File name field; specified as nine characters that are stored in Radix-50 format 
N.FTYP 2 File type field; specified as three characters that are stored in Radix-50 format 
N.FVER 2 File version number field (binary) 

N.STAT 2 Filename block status word (See bit definitions in Table B—2.) 

N.NEXT 2 Context for next .FIND operation 

N.DID 6 Directory identification field 

N.DVNM 2 ASCIi device name field 

N.UNIT 2 Unit number field (binary) 


The bit definitions of the filename block status word (N.STAT) in the FDB and their significance 
are described in Table B—2. (Other bits are set as required by FCS and the Peripheral Interchange 
Program (PIP) for processing.) 


Table B-2 Filename Block Status Word (N.STAT) 


Symbolic 

Offset Value 

Name (Octal) Meaning 

NB.VER' 1 Set if explicit file version number is specified. 

NB.TYP" 2 Set if explicit file type is specified. 

NB.NAM' 4 Set if explicit file name is specified. 

NB.SVR 10 Set if wildcard file version number is specified. 

NB.STP 20 Set if wildcard file type is specified. 

NB.SNM 40 Set if wildcard file name is specified. 

NB.DIR’ 100 Set if explicit directory string User Identification Code (UIC) is specified. 
NB.DEV' 200 Set if explicit device name string is specified. 

NB.SD1? 400 Set if group portion of UIC contains wildcard specification. 
NB.SD2? 1000 Set if owner portion of UIC contains wildcard specification. 


‘Indicates bits that are set if the associated information is supplied through an ASCII data-set descriptor. 
2Although NB.SD1 and NB.SD2 are defined, they are neither set nor supported by FCS. 
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Filename Block 


Table B-2 (Cont.) Filename Block Status Word (N.STAT) 


Symbolic 

Offset Value 

Name (Octal) Meaning 

NB.ANS 2000 Set if file name ts in ANSI format. 

NB.WCH 4000 Set if wildcard character processing is required. 


The filename block format for ANSI magnetic tape file names is shown in Figure B-—2. 
Figure B-2 ANSI Filename Block Format 
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The filename block offset definitions for ANSI magnetic tape are shown in Table B-3. 


Table B-3 Filename Block Offset Definitions for ANSI Magnetic Tape 


Symbolic 

Offset Size 

Name (Bytes) Definition 

N.FID 2 File identification field 

N.ANM1 12 First 12 bytes of ANSI filename string 

N.FVER 2 File version number field (binary) 

N.STAT 2 Filename block status word (See bit definitions in Table B—2.) 


Filename Block 


Table B—3 (Cont.) Filename Block Offset Definitions for ANSI Magnetic Tape 


Symbolic 

Offset Size 

Name (Bytes) Definition 

N.NEXT 2 Context for next .FIND operation 
N.ANM2 6 Remainder of the ANSI filename string 
N.DVNM 2 ASCIl device name field 

N.UNIT 2 Unit number field (binary) 


File Header Block 


Table C—1 shows the format of the file header block. The various areas within the file header block 
are described in detail in the following sections. The offset names in the file header block may be 
defined either locally or globally, as shown in the following statements: 


FHDOF$ DEFSL 7DEFINE OFFSETS LOCALLY. 


FHDOF$ DEFSG 7;DEFINE OFFSETS GLOBALLY. 


Table C-1 File Header Block Format 


Size 
Area (Bytes) Content 


Header Area Identification area offset in words 


1 

1 Map area offset in words 

2 File number 

2 File sequence number 

2 Structure level and system number 


— Offset to file owner information, 
consisting of member number and 
group number 


1 Member number 

1 Group number 

2 File protection code 

1 User-controlled file characteristics 

1 System-controlled file characteristics 
3210 User file attributes 


— Size in bytes of header area of file 
header block. 


Identification 6 File name (Radix-50) 
Area 


File type (Radix-50) 

File version number (binary) 
Revision number 

Revision date 

Revision time 

Creation date 

Creation time 


Expiration date 


~ NON ON DY DD ND 


To round up to word boundary 


Offset 


H.IDOF 
H.MPOF 
H.FNUM 
H.FSEQ 
H.FLEV 
H.FOWN 


H.PROG 
H.PROJ 
H.FPRO 
H.UCHA 
H.SCHA 
H.UFAT 

S.HDHD 


|.-FNAM 


|.FTYP 
|.FVER 
1.RVNO 
|.RVDT 
L.RVTI 
I.CRDT 
1.CRTI 
1.EXDT 


. 
A) 


1 


File Header Block 


Table C-1 (Cont.) File Header Block Format 


Size 
Area (Bytes) Content Offset 
— Size (in bytes) of identification area of S.IDHD 
file header block 
Map Area 1 Extension segment number M.ESQN 
1 Extension relative volume number (not M.ERVN 
implemented) 
Extension file number M.EFNU 
Extension file sequence number M.EFSQ 
Size (in bytes) of the block count field M.CTSZ 
of a retrieval pointer (1 or 2); only 1 is 
used 
1 Size (in bytes) of the logical block M.LBSZ 
number field of a retrieval pointer (2, 
3, or 4); only 3 is used 
1 Words of retrieval pointers in use in M.USE 
the map area 
1 Maximum number of words of retrieval M.MAX 
pointers available in the map area 
— Start of retrieval pointers -  M.RTRV 
— Size in bytes of map area of file S.MPHD 
header block 
Checksum 2 Checksum of words 0-255 H.CKSM 


Word 


NOTE: The checksum word is the last word of the file header block. Retrieval pointers 
occupy the space from the end of the map area to the checksum word. 


Header Area 
The information in the header area of the file header block is described in Table C—2. 


Table C-—2 File Header Block Contents 
Word Area Contents 


Identification area offset Word 0, bits 0-7. This byte locates the start of the identification area relative to the 
start of the file header block. This offset contains the number of words from the start 
of the header to the identification area. 


Map area offset Word 0, bits 8-15. This byte locates the start of the map area relative to the start of 
the file header block. This offset contains the number of words from the start of the 
header area to the map area. 


File number The file number defines the position this file header block occupies in the index file; for 
example, the index file is number 1, the storage bit map is fille number 2, and so forth. 


File sequence number The file number and the file sequence number constitute the file identification number 
used by the system. This number is different each time a header Is reused. 
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Table C-2 (Cont.) File Header Block Contents 


Word Area 


Structure level 


Fite owner information 


File protection code 


File characteristics 


User file attributes 


Identification Area 


Contents 


This word identifies the system that created the file and indicates the file structure. A 
value of [1,1] is associated with all current Files-11 volumes. 


This word contains the group number and owner number constituting the User 
Identification Code (UIC) for the file. Legal UICs are within the range [1,1] to [377,377]. 
However, UIC [1,1] is reserved for the system. 


This word specifies the manner in which the file can be used and who can use it. 
When creating the file, you specify the extent of protection desired for the file. 
This word, consisting of two bytes, defines the status of the file. Following Is a 
description of each byte: 

Byte 0 defines the user-controlled characteristics. They are as follows: 


UC.CON = 200 Logically contiguous file. When the file is extended (for example, 
by a WRITE$ or PUT$ macro), bit UC.CON is cleared whether or 
not the extension requests contiguous blocks. 


UC.DLK = 100 File improperly closed. 

Byte 1 defines system-controlled characteristics. They are as follows: 
SC.MDL = 200 ‘File marked for deletion. 

SC.BAD = 100 Bad data block in file. 


This area consists of 16 words. The first seven words of this area are a direct image 
of the first seven words of the FDB when the file is opened. The other nine words of 
the record I/O control area are not used by FCS, although RMS does use them. 


Information in the identification area of the file header block is detailed in Table C—3. 


Table C-3 File Header Indentification Area Contents 


Word Area 


File name 


File type 
File version number 


Revision number 


Revision date 


Revision time 


Contents 


The file's creator specifies a file name of up to nine Radix-50 characters In length. 
This name is placed in the name field. The unused portion of the field (if any) is 
zero-filled. 


This word contains the file type in Radix-50 format. 


This word contains the file version number, in binary, as specified by the creator of 
the file. 


This word is initialized to 0 when the file is created; it is incremented each time a 
file is closed after being updated or modified. 


Seven bytes are used to maintain the date on which the file was last revised. The 
revision date is kept in ASCII form in the format day,. month, year (two bytes, three 
bytes, and two bytes, respectively). This date is meaningful only if the revision 
number is a nonzero value. 


Six bytes are used to record the time at which the file was last revised. This 
information is recorded in ASCII form in the format hour, minute, and second (two 
bytes each). 
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File Header Block 


Table C-3 (Cont.) File Header Indentification Area Contents 


Word Area Contents 

Creation date The date on which the file was created is kept in a 7-byte field having the same 
format as that of the revision date (see above). 

Creation time The time of the file's creation is maintained in a 6-byte field having the same 
format as that of the revision time (see above). 

Expiration date The date on which the file becomes eligible to be deleted is kept in a 7-byte field 


having the same format as that of the revision date (see above). Use of expiration 
is not implemented. 


Map Area 


The map area contains the information necessary to map virtual block numbers to logical block 
numbers. This is done by means of retrieval pointers, each of which points to an area of contiguous 
blocks. A retrieval pointer consists of a count field and a number field. The count field defines the 
number of blocks contained in the contiguous area pointed to while the logical block number (LBN) 
field defines the block number of the first logical block in the area. 


A value of n in the count field (see Figure C—1) means that n+1 blocks are allocated, starting at the 
specified block number. 


Figure C~—1 shows the retrieval pointer format used in the Files-11 file structure. 


Figure C-1 Retrieval Pointer Format 
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The map area normally has space for 102 retrieval pointers. It can map from 102 to 26,112 blocks. 
If more retrieval pointers are required, extension headers are allocated to hold additional retrieval 
pointers. Extension headers are allocated within the index file. They are identified by a file 
number and a file sequence as are other file headers; however, extension file headers do not appear 
in any directory. 


A nonzero value in the extension file number field of the map area indicates that an extension 
header exists. The extension header is identified by the extension file number and the extension 
file sequence number. The extension segment number numbers the headers of the file sequentially, 
starting with a 0 for the initial header. . 


File Header Block 


Extension headers of a file contain a header area and identification area that are a copy of the first 
header as it appeared when the first extension was created. Extension headers are not updated 
when the first header of the file is modified. 


Extension headers are created and handled by the file control primitives as needed; their use is 
transparent to you. 


D Statistics Block 


The format of the statistics block is shown in Figure D—1. The statistics block is allocated manually 
in your program as described in Chapter 3. 


Figure D-1_ Statistics Block Format 
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Index File Format 


The index file ((0,0JINDEXF.SYS) of a Files-11 volume consists of virtual blocks, starting with 
virtual block 1, the bootstrap block. Virtual block 2 is the home block. Table E—1 describes the 
structure and contents of an index file. 


Table E-1 Index File Structure 


Virtual Block 
Number Index File Element 
1 Bootstrap block 
2 Home block 
3 Index file bit map (n blocks); the value of n is in the home block 
3+n Index file header 
3+n+1 Storage map header 
34n+2 Bad block file header 
3+N+3 Master File Directory (MFD) header 
3+n+4 Checkpoint file header 
34+n+5 User file header 1 
3+n+6 User file header 2 


User file header n 


Bootstrap Block 


A disk that is structured for Files-11 has a 256-word block, starting at physical block 0. This block 
contains either a bootstrap routine or a message to the operator stating that the volume does 

not contain a bootable system. The bootstrap routine brings a core image into memory from a 
predefined location on the disk. 


Home Block 


The home block contains volume identification information that is formated as shown in Table E-2. 
This block is located either in logical block 12 or at any even multiple of 256 blocks. In addition, 
you can define offset names in the home block locally or globally by using the following commands: 


HMBOF$ DEFSL ;DEFINES OFFSETS LOCALLY. 
HMBOF$ DEFSG ;DEFINES OFFSETS GLOBALLY. 
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Index File Format 


Table E-2_ Home Block Format 


Size 

(Bytes) Content Offset 

2 Index bit map size H.IBSZ 

4 Location of index bit map H.IBLB 

2 Maximum files allowed H.FMAX 

2 Storage bit map cluster factor H.SBCL 

2 Disk device type H.DVTY 

2 Structure level H.VLEV 

1240 Volume name (12 ASCII characters) H.VNAM 

4 Reserved - 

2 Volume owner's UIC H.VOWN 

2 Volume protection code H.VPRO 

2 Volume characteristics V.VCHA 

2 Default file protection word H.DFPR 

6 Reserved | - 

1 Default number of retrieval pointers H.WISZ 
in a window 

1 Default number of blocks to extend files H.FIEX 

1 Number of entries in directory least H.LRUC 
recently used (LRU) 

1110 Available space - 

2 Checksum of words 0-28 H.CHK1 

1440 Creation date and time H.VDAT 

10040 Volume header label (not used) - 

8210 System-specific information (not used) - 

25410 Relative volume table (not used) - 

210 Checksum of home block H.CHK2 
(words 0-255) 

Index File Bit Map 


The index file bit map controls the use of file header blocks in the index file. The bit map contains 
a bit for each file header block contained in the index file. The bit for a file header block is located 
by means of the file number of the file with which it is associated. The values of the bit map are as 
follows: 


0 Indicates that the file header block is available. 
The file control primitives can use this block to create a file. 


Indicates that the file header block is in use. 
This block has already been used to create a file. 


—_ 
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index File Format 


Predefined File Header Blocks 


The first five file header blocks of an index file are predefined. Table E—3 describes the contents of 
the predefined blocks. 


Table E-3 Predefined File Header Blocks 


File Header Block Description 

Index File Header This is the standard header associated with the index file. 

Storage Map File The storage map is a file that is used to control the assignment of disk blocks to 

Header files. 

Bad Block File Header The bad block file is a file that consists of unusable blocks (bad sectors) on the 
disk. 

Master File Directory This header block is associated with the Master File Directory (MFD) for the disk. 

Header This directory contains entries for the index file, the storage map file, the bad block 
file, the MFD, the checkpoint file, and all User File Directories (UFDs). 

Checkpoint File Header This block identifies the file that is used for the checkpoint areas for all 
checkpointable tasks. A task can also have checkpoint space in the task image 
itself. 
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Summary of /O-Related System Directives 


Table F—1 contains a summary of the I/O-related system directives in alphabetical order. The 
parameters you can specify with a directive are also described in the order of their appearance 
in the directive. These directives are described in detail in the JAS Executive Facilities Reference 
Manual. 


Table F-1 Summary of I/O-Related System Directives 


Directive Function and Parameters 

ALUNS Assign Logical Unit Number 
Assigns a logical unit number (LUN) to a physical device. 
Format 


ALUN$ _lun,dev,unt 


lun Specifies the logical unit number (LUN). 
dev Specifies the physical device name (two ASCII characters). 
unt Specifies the physical device unit number. 
GLUNS Get Logical Unit Number Information 
Fills a 6-word buffer with information about a physical unit to which the LUN is assigned. 
Format 


GLUNS __lun,buf 


lun Specifies the logical unit number (LUN). 
buf Specifies the address of a 6-word buffer in which the LUN information is to be stored. 
GMCR$ Get MCR Command Line 


Transfers an 80-byte Monitor Console Routine (MCR) command line to the task issuing GMCR$. 
No parameters are required in this directive. 


QIO$ Queue I/O Request 
Places an I/O request in the device queue associated with the specified LUN. 
Format 


QIO$ fnc,lun,efn,pri,isb,ast, pri 


fne Specifies the I/O function code. 

lun Specifies the logical unit number (LUN). 

efn Specifies the event flag number. 

pri Specifies the priority of the request (ignored but must be present.) 

isb Specifies the address of the I/O status block (IOSB). 

ast Specifies the entry-point address of the asynchronous system trap (AST) service routine. 
pri Specifies the parameter list in the form <P1,...,P6>. 


Summary of I/O-Related System Directives 


Table F-1 (Cont.) Summary of I/O-Related System Directives 


Directive 


Qlows 


RCST$ 


RCVD$ 


RCVX$ 


Function and Parameters 


Queue I/O Request and Wait 


Places an I/O request in the device queue associated with the specified LUN. The Executive 
suspends the task until the specified event flag is set. 


Format 


QIOWS$S fne,lun,efn,pri,isb,ast,prl 


fne Specifies the I/O function code. 

lun Specifies the logical unit number (LUN). 

efn Specifies the event flag number (EFN). 

pri Specifies the priority of the request (ignored but must be present.) 
isb Specifies the address of the I/O status block (IOSB). 

ast Specifies the entry-point address of the AST service routine. 

pri Specifies the parameter list in the form <P1,...,P6>. 


Receive Data or Stop 
Instructs the system to dequeue a 13-word data block for the task issuing RCST$. 
Format 


RCST$ tname,buf 


tname Specifies the name of the sending task (if not specified, data can be received from any 
task.) 


buf Specifies the address of a 15-word buffer to receive the sender task name and data. 
Receive Data 

Receives a 13-word data block that has been queued (FIFO). 

Format 


RCVD$ tsk,buf 


tsk Specifies the name of the sending task. 


buf Specifies the address of the 15-word data buffer (2-word sending task name and 
13-word data block.) 


Receive Data or Exit 
Receives a 13-word data block if queued. 
Format 


RCVX$ tsk,buf 


tsk Specifies the name of the sending task (if not specified, data can be received from any 
task.) 
buf Specifies the address of the 15-word data buffer (2-word sending task name and 


13-word data block.) 
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Table F-1 (Cont.) Summary of I/O-Related System Directives 


Directive 


VRCD$ 


VRCS$ 


VRCX$ 


Function and Parameters 


Variable Receive Data 


Instructs the system to dequeue a variable length data block for the task issuing VRCD$. The 
block was queued by the Variable Send Data directive. If you specify the sending task, only data 
sent by that task is received. 


Format 


VRCD$ task,bufadr,buflen 


task Specifies the sender task name. 
bufadr Specifies the buffer address. 


buflen Specifies the buffer size in words (256,, words maximum). The default is 1319 words. 
The first two words are the sender task name. The data block follows. 


Variable Receive Data or Stop 


Instructs the system to dequeue a variable-length data block for the task issuing VRCS$. The 
block was queued by a Variable Send Data directive. If there is no packet, the task issuing VRCS$ 
is stopped. The sending task is expected to issue an Unstop directive after sending the data. 
When you specify a sender task, only data sent by that task is received. 


Format 


VRCS$ task,bufadr,buflen 


task Specifies the sender task name. 
bufadr Specifies the buffer address. 


buflen Specifies the buffer size in words (256,) words maximum). The default is 131. words. 
The first two words are the sender task name. The data block follows. 


Variable Receive Data or Exit 


Instructs the system to dequeue a variable-length data block for the issuing task. The data block 
was queued for the task by a Variable Send Data directive. If you specify a sender task, only data 
sent by that task is received. If no data has been sent to the task issuing VRCX$, the task exits. 


Format 


VRCX§ task,bufadr,buflen 


task Specifies the name of the sending task. 
bufadr Specifies the buffer address. 


buflen Specifies the buffer length (a maximum of 25619 words). The default is a minimum of 
1319 words. The first two words are the sender task name. 
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Table F—1 (Cont.) Summary of 1/O-Related System Directives 


Directive Function and Parameters 


VSDA$ Varlable Send Data 


Instructs the system to queue a variable-length data block for the specified task to receive. If you 
specify an event flag, a significant event is declared when the directive executes successfully. 


Format 
VSDA$ task,bufadr,buflen 


task Specifies the receiving task name. 
bufadr § Specifies the buffer address. 


buflen Specifies the buffer size in words (a maximum of 25610 words). The default is 134 
words. 
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Support of ANSI Magnetic Tape Standard 


This appendix defines the American National Standards Institute (ANSI) magnetic tape labeling 
standard, which is a level three implementation of the ANSI standard, Magnetic Tape Labels and 
File Structure for Information Interchange (X3.27-1978). The exceptions are that ANSI does not 
support spanned records and that Digital’s tape system does not support user-supplied labels. 
User-supplied labels might appear on a tape; however, they are accessible to application programs 
only through the unlabeled tape feature. 


Volume and File Labels 
Tables G—-1, G-2, G—3, and G-4 present the format of volume labels and file header labels. 


Volume Label Format 
Table G—1 describes the volume label format for ANSI magnetic tape. 


Table G-1 Volume Label Format 


Character Length 

Position Fieid Name (Bytes) Contents 

1-3 Label identifier 3 VOL 

4 Label number 1 1 

5-10 Volume identifier 6 Contains the volume label and any ANSI “a” character. An 
“a” character is defined by the ANSI standard as any of 
the uppercase letters A—Z, the digits 0-9, and the following 
special characters: 
space !"% &' () * +, -./ 8 3 <=> ?) 

11 Accessibility 1 Contains any ANSI “a” character. A space indicates no 
restriction. You can specify the “a” character with the 
/VOLUME_ACCESSIBILITY:"c” qualifier in the DCL command 
INITIALIZE. Any ANSI “a” character is allowed. The default 
character is a space. Refer to the [AS MCR User's Guide 
or the [AS Command Language Reference Manual for more 
information on INITIALIZE. 

12-37 Reserved 26 Spaces 

38-51 Owner 14 The contents of this field are system dependent and are used 

identification for volume protection purposes. See Section G.1.1.1. 
52-79 Reserved 28 Spaces . 
80 label standard 1 3 
version 


Support of ANSI Magnetic Tape Standard 


G.1.1.1 Contents of Owner Identification Field 
The owner identification field is divided into the following three subfields and a single pad 
character: 


1 System identification (positions 38 to 40) 
2 Volume protection code (positions 41 to 44) 
3 User Identification Code (UIC) (positions 45 to 50) 


4 A numeric 1 (position 51) 


The system identification consists of the following character sequence: 
D%x 
The machine code is indicated by x, which can be one of the following: 


8—PDP-8 
A—DECsystem-10 
B—PDP-11 
F—PDP-15 


The D%x characters provide an identification method so that the remaining data in the owner 
identification field can be interpreted. The /OWNER switch to the MCR command INI allows you 
to overwrite these characters. The /OWNER=“owner” qualifier to the DCL command INITIALIZE 
allows you to overwrite these characters. (Refer to the IAS MCR User’s Guide and the IAS 
Command Language Reference Manual for more information. In the case of tapes produced on 
PDP-11 systems, the default system identification is D%B and the volume protection code and UIC 
are interpreted as described in the list that follows. 


The volume protection code in positions 41 to 44 defines access protection for the volume for four 
classes of users. Each class of user has access privileges specified in one of the four columns, as 
follows: 


Position Class 

41 System (UIC no greater than [7,255]1o0) 

42 Owner (group and member numbers match) 
43 Group (group number matches) 

44 World (any user not in one of the above) 


One of the following access codes can be specified for each character position: 


Code _ Privilege 


0 No access 

1 Read access only 

2 Extend (append) access 

3 Read/extend access . 
4 Total access 


The UIC is specified in character positions 45 to 50. The first three characters are the group code 
in decimal. The next three are the user code in decimal. 


The last character in the owner identification field is a numeric 1. 
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Support of ANSI Magnetic Tape Standard 


The following is an example of the owner identification field: 


3 


Owner identifier - D%*B14100631461 
The file was created on a PDP-11. 


System and group have read access. 
Owner has total access. 
All others are denied access. 


The UIC is [063,146]. 


User Volume Labels 


User volume labels are never written or passed back to you. If present, they are skipped. 


File Header Labels 


You should consider the following information before creating file header labels: 


The Files-11 naming convention uses a subset (Radix-50) of the available ANSI character set 
for file identifiers. 


One character in the file identifier, the period (.), is fixed by Files-11. 
A maximum of 13 of the 17 bytes in the file identifier are processed by Files-11. 


It is strongly recommended that all file identifiers be limited to the Radix-50 PDP-11 character 
set, and that no character other than the period (.) be used in the file type delimiter position 
for data interchange between PDP-11 and DECsystem-10 systems. 


For data interchange between DIGITAL and non-DIGITAL systems, the preceding conventions 
should be followed. If they are not, refer to Section G.1.3.1. 


Tables G—2, G—3, and G4 describe the HDR1, HDR2, and HDR3 labels, respectively. 


Table G-2 File Header Label (HDR1) 
Character Length 


Position Fleld Name (Bytes) Contents 

1-3 Label identifier 3 HDR 

4 Label number s| 1 

5-21 File identifier 17 Contains any ANSI “a” character. See Table G—1. 

22-27 File set 6 Contains the volume identifier of the first volume in the set of 
identifier volumes. 

28-31 File section 4 Contains numeric characters. This field starts at 0001 and is 
number increased by 1 for each additional volume used by the file. 

32-35 File sequence 4 Contains the file number within the volume set for this file. 
number This number starts at 0001. 

36-39 Generation number 4 Contains numeric characters. 

40-41 Generation version 2 Contains numeric characters. 
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Table G-2 (Cont.) File Header Label (HDR1) 


Character Length 
Position _Fleld Name (Bytes) Contents 
42--47 Creation date 6 _yyddd (_ indicates space) 
or 
_00000 if no date 
48--53 Expiration date 6 Same format as creation date. 
54 Accessibility 1 Space 
55--60 Block count 6 000000 
61-73 System code 13 Contains the three letters DEC, followed by the name of the 
system that produced the volume. See Section G.1.1.1. 
Examples: DECFILE11A DECSYSTEM10 
Pad name with spaces. 
74-80 Reserved 7 Spaces 
Table G-3 File Header Label (HDR2) 
Character Length 
Position Fleid Name (Bytes) Contents 
1-3 Label identifier 3 HDR 
4 Label number 1 2 
5 Record format 1 F indicates fixed length. 
D indicates variable length. 
S indicates spanned. 
U indicates undefined. 
6-10 Block length 5 Contains numeric characters. 
11-15 Record length 5 Contains numeric characters. 
16--50 System-dependent 35 Positions 16 to 36 are spaces. 
information Position 37 defines carriage control and can contain one of 
the following: 
A Indicates first byte of record contains FORTRAN 
control characters. 
space Indicates line feed/carriage return is to be inserted 
between records. 
M Indicates the record contains all form control 
information. 
lf DEC appears in positions 61 to 63 of HDR1, position 37 
must be as previously specified. 
Positions 38 to 50 contain spaces. _ 
51-52 Buffer offset 2 Contains numeric characters; 00 on tapes produced by 
Files-11. Supported only on input to Files-11. 
53--80 Reserved 28 Spaces 


Table G-4 File Header Label (HDR3) 
Character ~~ Length 
Position Field Name (Bytes) 
1-3 Label identifier 3 

4 Label number 1 

5-68 System-dependent 64 
69-80 Reserved 10 
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Contents 


HDR 
3 


Contains file attributes specified at creation time. Each of 
the 32 bytes of user file attributes is expanded into two 
hexadecimal characters. The first seven words of this 

area are a direct image of the first seven words of the File 
Descriptor Block (FDB) when the file is opened. These are 
the same words in the file-attribute section of the FDB given 
in Appendix A. The other nine words are not used by File 
Control Services (FCS) though they are used by Record 
Management Services (RMS). 


The following list translates the user file attribute bytes to the 
corresponding hexadecimal character pair: 


Byte Pair Byte Pair 


1 4 17 20 
2 3 18 19 
3 2 19 18 
4 1 20 17 
5 8 21 24 
6 7 22 23 
7 6 23 22 
8 5 24 21 
9 12 25 28 

10 11 26 27 

11 10 27 26 

12 9 28 25 

13 16 29 32 

14 15 30 31 

15 14 31 30 

16 13 32 29 


Using the list, the eighth hexadecimal character pair is 

the expansion of the fifth user file attribute byte, and the 
fourth user file attribute byte is expanded into the first 
hexadecimal character pair. The hexadecimal pair is the 
normal representation of the contents of the byte; that is, if 
the byte contains a 15,9, the hexadecimal representation of it 
is OF, 


Spaces 
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G.1.3.1 File Identifier Processing by Files-11 


The magnetic tape Ancilliary Control Processor (ACP) processes Files-11 type file identifiers. 
However, if the file name is enclosed in quotes, it is processed as an ANSI file name, all “a” 
characters are legal, all 17 positions can be used, and the only conversion that takes place is 
making all lowercase characters into uppercase characters and converting all characters that are 
not “a” characters to question marks. 


At file input, the file identifier is handled as follows: 


1 


The first nine characters at a maximum are processed by an ASCII-to-Radix-50 converter. The 
conversion continues until one of the following occurs: 


a. A conversion failure occurs. 
b. Nine characters are converted. 
c. A period (.) is encountered. 


If the period is encountered, the next three characters after the period are converted and 
treated as the file type. If a failure occurs or all nine characters are converted, the next 
character is examined for a period. If it is a period, it is skipped and the next three characters 
are converted and treated as the file type. 


The version number is derived from the generation number and the generation version number 
is as follows: 


(generation number - 1)*100 + generation version + 1 


If an invalid version number is computed, it will be changed to 1. 


At file output, the file identifier is handled as follows: 


1 


The file name is placed in the first positions in the file identifier field. It can occupy up to nine 
positions and is followed by a period. 


The file type of up to three characters is placed after the period. The remaining positions are 
padded with spaces. 


The version number is then placed in the generation and generation version number fields, as 
described in the following formulas: 


: ston 
a. Generation number = ("$657") +1 
b. Generation version # = version # —1 Modulo 100 


(Note that, in both calculations, remainders are ignored.) 


The following are examples of Files-11 versions and their generation version numbers. 


Files-11 Generation 
Version No. Generation No. Version No. 
1 1 0 
50 1 49 
100 1 99 
101 2 0 
1010 11 9 
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End-of-Volume Labels 


End-of-volume labels are identical to the file header labels, with the following exceptions: 
¢ Character positions 1 to 3 contain EOV instead of HDR. 


e The block count field contains the number of records in the last file section on the volume. 


File Trailer Labels 


End-of-file labels (file trailer labels) are identical with file header labels, with the following 
exceptions: 


¢ Columns 1 to 3 contain EOF instead of HDR. 


¢ The block count contains the number of data blocks in the file. 


User File Labels 


User file labels are never written or passed back to you. If present, they are skipped. 


File Structures 


The file structures illustrated below are the types of file and volume combinations that the file 
processor produces. The file processor can read and process additional sequences. 


The minimum block size and fixed-length record size is 18 bytes. The maximum block size is 8192 
bytes. FCS adapts to input files of varying block size. 


If HDR2 is not present, the data type is assumed to be fixed (F), and the block size and record size 
are assumed to be the default value for the file processor. The default for both block and record 
size is 51219 bytes. You can override these block and record sizes with the MAG command (see 
Section G.5), and the MOUNT command. The MAG command controls block and record size on 
unlabeled tapes and on ANSI level 1 and 2 tapes. 


The meaning of the symbols used in the file structure illustrations is as follows: 


1 The asterisk (*) indicates a tape mark. As defined by ANSI, a tape mark is a special control 
block recorded on magnetic tape to serve as a separator between files and file labels. 


BOT indicates beginning of tape. 
EOT indicates end of tape. 


The comma (, ) indicates the physical record delimiter. 


File Structure Format 


Table G—5 lists the various file structures and their format. 
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Table G-—5 File Structures 


File/Volume 

Combinations Structure Format 

Single File BOT,VOL1,HDR1,HDR2,HDR3*—DATA—*EOF1 ,EOF2,EOF3** 
Single 

Volume 

Single File BOT,VOL1,HDR1,HDR2,HDR3*—DATA—*EOV1,EOV2,EOV3** 
Multivolume BOT,VOL1,HDR1,HDR2,HDR3*—DATA—*EOF1 ,EOF2,EOF3** 

Multifile BOT,VOL1,HDR1,HDR2,HDR3*—DATA—*EOF1 ,EOF2,EOF3*HDR1, 
Single HDR2,HDR3*—DATA—"EOF1,EOF2,EOF3** 

Volume 

Multifile BOT,VOL1,HDR1,HDR2,HDR3*—DATA—“EOF1 ,EOF2,EOF3*HDR1,HDR2, 


Multivolume HDR3*—DATA-—“EOV1,EO V2,EOV3"" 
BOT, VOL1,HDR1,HDR2,HDR3*—DATA—“EOF1 ,EOF2, EOF3*HDR1,HDR2, 
HDR3*—DATA—* EOF1 ,EOF2,EOF3** 


End-of-Tape Handling 


End-of-tape is handled by the magnetic tape file processor. Files are continued on the next volume 
provided that the volume is already mounted or mounted upon request. A request for the next 
volume is printed on CO (console output pseudo device). 


ANSI Magnetic Tape File Header Block (FCS Compatible) 


Figure G—1 illustrates the format of a file header block that is returned by the file header READ 
ATTRIBUTE command for ANSI magnetic tape. The header block is constructed by the magnetic 
tape primitive from data within the tape labels. . 


Example Using an Indirect Command File to Read a Tape 


The following example shows how to read a tape by using an indirect command file: 


° 
ce] 
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Figure G-1 ANSI Magnetic Tape File Header Block (FCS Compatible) 


H.MPOF IDENT Offset H.IDOF 
File Sequence Number H.FNUM 
File Section Number H.FSEQ 
Structure Level = 401g H.FLEV 
Header Area UIC (For Volume H.FOWN=H.PROG 
Protection Code (For Volume) H.FPRO 
Record Attributes Record Type Code H.UFAT 
Record Size in Bytes 
n Words of Zeros 
X+1.FNAM 
__File Name RADSO (IDENT Offset *2)=X 
File Type RADSO LFTYP 
File Version Number X+LFVER 
Zeros (Revision Date and Time) X+IL.RVNO 
Identification __Creation Date and Time (000000) X+I.CRDT 
Area Expiration Date X+1.EXDT 
Pad Byte of Zero X+47149 
Copy of the X+5019 
HDR1 Label 
Copy of the HDR2 Label 
(if byte 1 of label = 0, X+130 19 
label is not present). 
Map Area Null Map, That Is, Zeros X+21040- 
(10 Bytes Long) (Map of Offset 2) 


-ENABLE QUIET 
-ENABLE SUBSTITUTION 


-? This command file is invoked with the command 
@MTA outspec=Mx:infile 
and searches a tape mounted unlabeled (which has an ANSI-like structure) 
for the file "infile" and copies it to outspec. 
Parse the command line; OUTSPC gets outspec, 
DEV gets Mx, 
INFILE gets the file name to find on tape. 


e s s ° e s e 
se Ne Me Me Ne Se Ne 


-PARSE COMMAN " " OUTSPC COMMAN 
«PARSE COMMAN "=" OUTSPC INSPEC 
«PARSE INSPEC ":" DEV INFILE 
«IF INFILE EQ "" .GOTO NOTMT 


«SETS INFILE INFILE+" - 
oSETS INFILE INFILE[(1:17.] 

SETS JUNK DEV[1:1] 

»IF JUNK NE "M" .GOTO NOTMT 


e 
bat 4 
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-; Make a name for the temp file. 
-TESTFILE TI: 

-PARSE <FILSPC> ":" TMP JUNK 
-SETS TMP TMP+".TMP" 


-; Always start at the beginning of the tape. 
MAG SET 'DEV’ :/REWIND 

ae 

-; Labels have a block and record size of 80. 

MAG SET 'DEV’:/BS:80./RS:80. 

- LOOK: 

-7 Put the labels in a temp file so Indirect can look at them 

PIP 'TMP’='DEV’ :DUMMY.NAM 

»-OPENR ' TMP’ 

-READLB: 

-READ LABEL 

-IFT <EOF> .GOTO NOSUCH 

-SETS LABELT LABEL[{1:3] 

-; Skip any Volume header labels 
-IF LABELT = "VOL" .GOTO READLB 

-IF LABELT NE "HDR" .GOTO ILLFMT 

-SETS LABELT LABEL[4:4] 

-IF LABELT NE "1" .GOTO ILLFMT 

-SETS LABELT LABEL[5:21.] 

-7 If the names do not match, go get the next set of labels. 

-IF LABELT NE INFILE .GOTO TRYNXT 

-; We have found the file, see if there is a HDR2 with size info. 

-READ LABEL 

-IFT <EOF> .GOTO READFL 

-SETS LABELT LABEL[1:4] 

-IF LABELT NE “HDR2" .GOTO READFL 

-? Yes, we have a HDR2 label. 

-SETS LABELT LABEL[37.:37.] 

-SETS cc "LI" 

-IF LABELT = "A" .SETS CC "FO" 

.IF LABELT = "M" .SETS CC "NO" 

-SETS BS LABEL[6:10.] 

-SETS RS LABEL[11.:15.] 

-; Set up the block size, record size, and carriage control 

-? based on what was in HDR2. 

MAG SET ‘/DEV’:/BS:’BS’ ./RS:'’RS’./CC:'’CC’ 

-SETS LABELT LABEL[5:5] 

-IF LABELT EQ "F" .GOTO READFL 

-DISABLE QUIET 

!MTA - Warning, Record Format is 'LABELT’; only F Format is fully 

-ENABLE QUIET 

-READFL: 

-CLOSE 

-; Transfer the file. 

PIP ‘OUTSPC’ =’ DEV’ :"POS=1" 

-GOTO ENDIT 

» TRYNXT: 

.CLOSE 

MAG SET ‘DEV’ :/POS=3 

-GOTO LOOK 


suppoz 
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- ILLFMT: 
-DISABLE QUIET 
-DISABLE MCR 
MTA - Tape is not in a format that I understand. 
-GOTO ENDIT 
-NOTMT: 
-DISABLE QUIET 
-DISABLE MCR 


MTA - Input file spec must specify a magnetic tape device and a file name. 
-EXIT 
-NOSUCH: 
-DISABLE QUIET 
-DISABLE MCR 
MTA - No such file -- '’INSPEC’ 
-ENDIT: 
-ENABLE MCR 
-ENABLE QUIET 
PIP ‘TMP’; /DE/NM 
»EXIT 
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QIO$ Interface to the ACPs 


This appendix describes the QIO$ level interface to the file Ancillary Control Processors (ACPs). 
These include F11ACP for Files-11 disks and MTAACP for American National Standards Institute 
(ANSI) magnetic tape. Because ACPs work in direct relation with the Executive, they are very 
effective and are able to perform operations that device drivers cannot. In addition, all IAS 
directives can be issued by ACPs. 


F11ACP supports the following QIO functions: 


Function Code Meaning 


10.CRE Create file 

10.DEL Delete file 

10.ACR Access file for read only 
1O.ACW Access file for read/write 
10.ACE Access file for read/write/extend 
10.DAC Deaccess file 

10.EXT Extend file 

1O.RAT Read file attributes 

1O.WAT Write file attributes 

10.FNA Find file name in directory 
1IO.RNA Remove file name from directory 
10.ENA Enter file name in directory 
10.ULK Unlock block 


MTAACP supports the following QIO functions: 


Function Code Meaning 


1O.FNA Find file by name 

10.ENA Enter name in directory (nonoperational) 
10.ACR Access for read only 

lO.ACW Access for read/write 

1IO.ACE Access for read/write/extend 

10.DAC Deaccess file 

1lO.RVB Read virtual block 

10.WVB Write virtual block 

1IO.EXT Extend file 


H.1 


H.1.1 


H.1.2 


H.1.: 


H.1.4 


QIO$ Interface to the ACPs 


Function Code Meaning 


10.CRE Create file 

1O.RAT Read attributes 
1O.APC ACP control 

1IO.APV Privileged ACP control 


How to Use the ACP QIO$ Functions 


Although the operations described in this appendix are normally performed by the file-access 
methods Record Management Services (RMS) and File Control Services (FCS), your application can 
issue the ACP QIO$s. Using ACPs allows you the opportunity to speed up processing time with 
device I/O because ACPs already contain device-specific structure. 


The required parameters for each QIO$ are described in the preceding section. The necessary steps 
for common operations are described in the following section. 


NOTE: The file identifier is the only way to refer to a file. 


Creating a File 

To create a file, perform the following tasks: 

1 Use IO.CRE to create the file. 

2 Enter the file in the Master File Directory (MFD) or a User File Directory (UFD) with IO.ENA. 


Opening a File 

To open a file, perform the following tasks: 

1 Use IO.FNA to find the file identifier of the directory in the MFD. 
2 Use IO.FNA to find the file identifier of the file in the directory. 

3 Access the file with IO.ACR, IO.ACW, or IO.ACE. 


Closing a File 
To close a file, deaccess the file with IO.DAC. 


Extending a File 

To extend a file, perform the following tasks: 

1 Use IO.FNA to find the file identifier if the file is not accessed. 
2 Use IO.EXT to extend the file. 
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Deleting a File 

To delete a file, perform the following tasks: 

1 Use IO.FNA to find the file identifier. 

2 Use IO.RNA to remove the directory name. 
3 Use IO.DEL to delete the file. 


Errors Returned by the File Processors 
The error codes returned by F11ACP and MTAACP are shown in Table H-1. 


Table H-1_ Fife Processor Error Codes 
Error 
Code Operations Explanation 


IE.ABO 1O.RVB/O.WVB Indicates that not all requested data was transferred by the 
device. 

1E.ALC Extend or create operation Indicates that the operation failed to allocate the file because of 
placement control or because of other related problems. 

IE.ALN An attempt to access a file Indicates that a file is already accessed on that logical unit 
number (LUN). 

IE.BAD Any function Indicates that a required parameter is missing, that a parameter 
that should not be present is present, that a parameter that must 
be disabled is enabled, or that a parameter value is invalid. 

{E.BDR Directory operations Indicates that you attempted a directory operation on a file that 
is not a directory, or that the specified directory is corrupted. 
This is usually caused by a 0 version number field. 

1E.BHD Any operation Indicates that a corrupt file header was encountered, or that the 
operation required a feature not supported by the file control 
processor (FCP) (such as multiheader support or support for 
unimplemented features). 

IE.BVR Directory operations Indicates that you attempted to enter a name in a directory with 
a negative or 0 version number. 

1E.BYT Any function This error is returned if the buffer specified is on an odd-byte 
boundary or is not a multiple of 4 bytes. 

1E.BTP Unlabeled Magtape Create Indicates an attempt was made to create an unlabeled tape file 
with a record type other than fixed. 

IE.CKS Any operation Indicates that the checksum of a file header is incorrect. 

IE.CLO File access operations Indicates that the file was locked against access by the 
“deaccess lock bit.” 

1E.DFU An allocation request Indicates that there is insufficient free disk space for the 
requested allocation. 

lIE.DUP An enter name operation Indicates that the name and version already exist. 

IE.EOF 10.RVB/1O.WVB/0.DEL On read operations, this indicates an attempt to read beyond 


end-of-file. On truncate operations, it indicates an attempt to 
truncate a file to a length longer than that allocated or that the 
file was already at EOF. 
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Table H-1 (Cont.) File Processor Error Codes 


Error 
Code 


IE.HFU 


IE.IFC 
IE.IFU 


IE.LCK 


1E.LUN 


IE.NOD 


IE.NSF 


1E.OFL 
1E.PRI 


IE.RER 


1E.SNC 


1IE.SPC 
1E.SQC 


IE.WAC 


IE.WAT 
IE.WER 


IE.WLK 


Operations 


An extended operation 


Returned by exec 
Create or extend operation 


Returned on file access, directory 
operations, and on truncate 


Any operation requiring a file ID 


All file operations that require pool 


All file operations 


Returned by exec 
Any operation 


Any operation 

Any operation 

Returned by exec 

Any operation 

File access operations 

Write attributes and deaccess 


Any operation 


Any operation requiring write 
access 


Explanation 


Indicates that the file header is full and cannot contain any more 
retrieval pointers and that adding an extension header is not 
allowed. When this error code is returned on a create operation, 
it indicates that the Index file could not be extended to allow a 
file header to be allocated. 


Indicates illegal function code. 


Indicates that there are no file headers available based on the 
parameters specified when the volume was initialized. 


Indicates that the file is already accessed by a writer and that 
shared write has not been requested or is not allowed. 


Indicates that file ID has not been supplied and that the file is 
not accessed on the LUN. 


Indicates that an I/O request failed because of IE.UPN, and that 
the FCP was unable to allocate required space from DSR or 
from secondary pool for data structures. 


Indicates that the specified directory entry does not exist, that a 
file corresponding to the file ID does not exist, or that the file is 
marked for deletion. 


Indicates that the device is off line. 


Indicates that the user does not have the required privilege for 
the requested operation, or that the user has not requested 

the proper access to the file if the file is already accessed (for 
example, in an attempt to write to a file that is accessed for __ 
read). This error code also indicates an attempt to do file 1/O to 
a device that is not mounted. 


Indicates that the FCP encountered a fatal device read error 
during an operation; the operation has been aborted. 


Indicates that the file number and the value contained in the 
header do not agree. This generally means that the header has 
gone bad because of a crash or a hardware error. 


Indicates an illegal buffer. 


Indicates that the file sequence number does not agree with the 
file header; usually indicates that the file has been deleted and 
the header has been reused. 


Indicates that the file is already write accessed and that lock 
against writers is requested. 


Indicates that the FCP encountered an invalid attribute. 


Indicates that the FCP encountered a fatal device write error 
during an operation. The operation has been aborted, but the 
disk structure might have been corrupted. 


Indicates that the volume is software write-locked. 
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QIO$ Parameter List Format 


The device-independent part of a file processing QlO$ parameter list is identical to all other QIO$ 
lists. The general QIO parameter list is described in detail in the JAS Device Handler Manual. 
The file processor QIO$s require the following six additional words in the parameter lists: 


Parameter word 1 Specifies the address of a 3-word block containing the file identifier. 
Parameter word 2 Specifies the address of the attribute list. 

Parameter words 3 Specifies the size and extend control information. 

and 4 

Parameter word 5 Specifies the window size information and access control. 
Parameter word 6 Specifies the address of the filename block. 


File Identification Block 


The File Identification Block is a 3-word block containing the file number and the file sequence 
number. The format of the File Identification Block is shown in Figure H-1. 


Figure H-1_ File identification Block 


File Number 


File Sequence Number 


Reserved 


F11ACP uses the file number as an index to the file header in the index file. Each time a header 
block is used for a new file, the file sequence number is incremented. This ensures that the file 
header is always unique. The third word is not currently used but is reserved for the future. 


The Attribute List 


The file attribute list controls F11ACP reads or writes. File attributes are fields in the file header. 
These fields are described in detail in Chapter 2. 


The attribute list contains a variable number of entries terminated by an all-0 byte. The maximum 
number of entries in the attribute list is six. 


An entry in the attribute list has the following format: 


.BYTE <Attribute type>, Attribute size 
WORD Pointer to the attribute buffer 
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H.3.2.1 The Attribute Type 


This field identifies the individual attribute to be read or written. The sign of the attribute type 
code determines whether the transfer is a read or write operation. If the type code is negative, the 
ACP reads the attribute into the buffer. If the type code is positive, the ACP writes the attribute 
to the file header. Note that the sign of the type code must agree with the direction implied by the 
operation. For example, if the type code is positive, the operation must be an IO.WAT or IO.DAC 
function code. 


The attribute type is one of the following: 


File owner (H.FOWN) 


The file owner User Identification Code (UIC) is a binary word. The low byte is the owner 
number and the high byte is the group number. 


File protection (H.FPRO) 
The file protection word is a bit mask with the following format: 


Each of the fields contains four bits, as follows: 


Bit 1 Read access 
Bit 2 Write access 
Bit 3 Extend access 
Bit 4 Delete access 


File characteristics (H.UCHA) 
The following user characteristics are currently contained in the 1-byte H.UCHA field: 


UC.CON = 200 Logically contiguous file 
UC.DLK = 100 File improperly closed 


Record I/O Area (U.UFAT) 


This field contains a copy of the first seven words of the File Descriptor Block (FDB). (RMS 
uses 32 bytes. The first seven are compatible with FCS for sequential files.) See Appendix A 
for a description of the FDB. 


File name (I.LFNAM) 


The file name is stored as nine Radix-50 characters. The fourth word of this block contains the 
file type and the fifth word contains the version number. 


File type (I.FTYP) 

The file type is stored as three Radix-50 characters. 

Version number (I.FVER) 

The version number is stored as a binary number. 

Expiration date (ILEXDT), creation date (IL.CRDT), revision date (ILRVDT) 


The expiration date is currently unused. When the file is created, the ACP initializes the 


. creation date to the current date and time. It initializes the expiration and revision dates to 0. 


The ACP sets the revision date to the current date and time each time the file is deaccessed by 
a write access routine. 


Statistics block 
This block is described in Appendix D. 
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¢ Read entire file header’ 
This buffer is assumed to be 1000g bytes long. You cannot write this attribute. 
e Revision number (I.RVNO) 


The ACP sets the revision number to 0, and the ACP increments it every time the file is 
deaccessed by a write access routine. 


¢ Placement control 


Placement control is described in Section H.4. 


H.3.2.2 Attribute Size 
This byte specifies the number of bytes of the attribute to be transferred. Legal values are from 
1 to the maximum size of the particular attribute. Table H-2 shows the maximum size for each 
attribute type. . 


Table H-2 Maximum Size for Each File Attribute 


Maximum 
Attribute Attribute Type 
Type Code Attribute Type (Octal Bytes) 
1 File owner 6 
2 Protection 4 
3 File characteristics 2 
4 Record I/O area 40 
5 File name, type, and version nurnber 12 
6 File type 4 
7 Version number 2 
10 Expiration date 7 
11 Statistics block 12 
12 Entire file header 0 
13 Block size (magnetic tape only) — 
15 Revision number and creation/revision/expiration 43 
dates 
16 Placement control 16 


H.3.2.3 Attribute Buffer Address 
The attribute buffer address field contains the address of the buffer in the user’s task space to or 
from which the attribute is to be transferred. 


Size and Extend Control 


The size and extend control parameters specify how many blocks the file processor allocates to a 


‘new file or adds to an existing file. These parameters also control the type of block allocation. 


The format is as follows: 


.BYTE <High 8 bits of size>, <extend control> 
WORD <Low 16 bits of size> 
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The size field specifies the number of blocks to be allocated to a file on IO.CRE and IO.EXT 
operations, and the field specifies the final file size on IO.DEL operations. 


The extend control field controls the manner in which an extend operation is to be executed. The 
following bits are defined: 


Bit Definition 

EX.AC1=1 The extend size is to be added as a contiguous block. 

EX.AC2=2 Extend by the largest available contiguous piece up to the specified size. 

EX.FCO=m4 The file must end up contiguous. 

EX.ADF=10 Use the default rather than the specified size. The default extend size is the size that was 
specified when the volume was mounted. 

EX.ALL=20 Placement control (see Section H.4). 


EX.ENA=200 Enable extend. 


Window Size and Access Control 


The window and access control parameter specifies the window size and access control informatio: 
in the following format: 


-BYTE <window size>, <access control> 
This word is only processed if the high bit of the access control byte (AC.ENB) is set. 


Window size is the number of mapping entries. Specifying a negative window size minimizes 
window turns. If this byte is zero, the file processor uses the volume default. The size of the 
window allocated in the pool is 6 times the number of mapping entries (each mapping entry is 3 
words), plus 10 bytes for the window control block. 


The following access control bits are defined: 


Bit Definition 
AC.LCK=1 Lock out further accesses for Write or Extend 
AC.DLK=x2 Enable deaccess lock 


The deaccess lock sets the lock bit in the file header if the file is deaccessed as the result of a 
task exit without explicitly deaccessing the file. The lock bit is set by the Executive. The lock bi 
is not set when the system crashes. 


AC.LKL=4 Enable block locking 

AC.EXL=10 Enable explicit block unlocking 

AC.ENB=200 Enable access 

AC.RWD=10 Rewind the volume (labeled and unlabeled magnetic tape only) 
AC.UPD=100 Update mode (labeled magnetic tape only) 
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Bit Definition 


AC.POS=20 Do not position to end-of-volume (labeled magnetic tape only) 
AC.WCK=40 Initiate driver write-checking 
NOTE: Both AC.LKL and AC.EXL must be set if you want block locking. 


If you do not want block locking, both bits must be clear. Any other 
combination is an error. 


Filename Block Pointer 


The filename block pointer contains the address of a 15-word block in the issuing task’s space. This 
block is called the filename block. The filename block is described in detail in Appendix B. 


The fields of the filename block that are particularly important in file-processing operations are as 
follows: 


¢ Directory identification (N.DID) 


This field is required for all disk operations. It specifies the directory to which the operation 
applies. This field is not used for tape operations. 


¢ File identification (N.FID) 


This field is required as input for enter operations. This field is returned as output by find and 
remove operations. 


e File name (N.FNAM), file type (N.FTYP), and file version number (N.FVER) 


These fields are required as input to enter, find, and remove operations. For find and remove 
operations, the file processor locates the appropriate entry by matching the information in | 
these fields with the directory entries. 


¢ Status word (N.STAT) 
¢ Wildcard context (N.NEXT) 


This field is required as input for wildcard operations. It specifies the point at which to resume 
processing. It is updated for the next operation. It must initially be set to 0. 


Placement Control 


The placement control attribute list entry controls the placement of a file in a particular place 
on the disk. You can specify either exact or approximate placement on IO.CRE and IO.EXT 
operations. 


The placement control entry must be the first entry in the attribute list. 
The format of the placement control attribute list entry is as follows: 


‘BYTE placement control,0 

WORD high-order bits of VBN or LBN 

WORK low-order bits of VBN or LBN 

.BLKW 4 Buffer to receive starting and ending LBN if AL.LBN is set. 
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The following bits are defined for the placement control field: 


Bit Definition 

AL.VBN=1 Set if block specified is a virtual block number (VBN); otherwise, the block is the logical block 
number (LBN). 

AL.APX=2 Set if you want approximate placement; otherwise, placement is exact. 

AL.LBN=4 Set if you want starting and ending LBN information. __ 

Block Locking 


Block locking only occurs when the user accesses a file with AC.LKL and AC.EXL set in the acces: 
control byte of the parameter list. Any read or write operation causes a check to see if the block is 
locked. 


A write access locks a block for exclusive access. A write operation can only access a block that 
is not locked by any accessor. The only exception to this is an exact match with a previous lock 
owned by the same accessor. 


A read access locks a block for shared access. A read operation can access any block locked for 
shared access. 


The user must unlock a block with the explicit unlock request, IO.ULK. You can use IO.ULK to 
unlock one or all locked blocks. 


If all accessors to a file have not requested block locking, the F11ACP returns an error (see 
Table H-1). 


When the file is deaccessed, all locks owned by the accessor are released. 


Each active lock requires 8 bytes from the system primary pool storage region. This storage is 
deallocated when the file is deaccessed. 


Summary of F11ACP Functions 


The following is a summary of the functions implemented in F11ACP. A list of accepted parameter 
follows each function. All parameters are required unless specified as optional. Parameters other 
than those listed are illegal for that function and must be 0. 


Function Parameter Meaning 
10.CRE Create file 
#1 Indicates the file identifier block is filled in with the file identifier and sequence 
number of the created file. 
#2 Indicates write attribute and/or placement control list (optional). 
#3 & #4 indicates extend control (optional). 
The amount allocated to the file is returned in the high byte of IOST(1) plus IOST(2 
#5 Might be nonzero but must be disabled. 
10.DEL Delete or truncate file 


Function 


10.ACR 
1O.ACW 
.10.ACE 


10.DAC 


10.EXT 


1O.RAT 


10.FNA 
10.RNA 
10.ENA 


10.ULK 


10.RVB 
1O.WVB 


Parameter 


#1 
#3 & #4 


#1 
#2 
#5 


#1 
#2 
#5 


#1 


#2 
#3 & #4 


#1 
#2 


#4 & #5 
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Meaning 


Optional if the file is accessed. 


Indicates size to truncate the file to. If not enabled, the file is deleted. If enabled, 
the remaining 31 bits specify the size the file Is to be after truncation. The change 
in file allocation is returned in the high byte of lIOST(1) plus IOST(2). This amount 
will be zero or negative. 


Access file for read only 

Access file for read/write 

Access file for read/write/extend 
Indicates file identifier pointer. 

Indicates read attributes control (optional). 
Indicates access control must be enabled. 
Deaccess file 


' Indicates file identifier pointer (optional). 


Indicates write attributes control list. 

Might be nonzero but must be disabled. 

Extend file 

Optional if file is accessed. 

Indicates placement control attribute list (optional). 

Indicates extend control. 

The amount allocated to the file is returned in the high byte of 1OST(1) plus IOST(2). 
Read attributes 

Optional if file is accessed. 

Indicates read attributes control list. 

Find name in directory 

Remove name from directory 

Enter name in directory 

Might be nonzero but must be disabled. 

Indicates filename block pointer. 

Unlock block 

Indicates 0 or count of blocks to unlock. 

Indicates starting virtual block number (VBN) to unlock or 0 to unlock all blocks. 
Read virtual block | 
Write virtual block 

Indicates user buffer. 

Indicates buffer length. 

Indicates virtual block number (VBN). 
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Summary of MTAACP Functions 


The following is a summary of the functions implemented in MTAACP. A list of accepted 
parameters follows each function. All parameters are required unless specified as optional. 
Parameters other than those listed are illegal for that function and must be 0. 


Function 


Parameter 


Meaning 


10.FNA 


10.ENA 
10.ACR 


1O.ACW 


10.ACE 


10.DAC 


1O.RVB 


10.CRE 
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#5 


#6 


#1 
#2 
#5 


#1 
#2 
#5 


#1 
#5 


#1 
#2 


#4 
#5 


Find file by name 


Indicates that the volume is to be rewound prior to the search when AC.RWD Is set 
in the access control byte. 


Indicates pointer to filename block. 
The following fields are used as input: N.FNAM, N.FTYP, N.FVER, and N.STAT. 


The following fields are returned by MTAACP: N.FID, N.FNAM, N.FTYP, N.FVER, 
and N.STAT. 


Enter name in directory — nonoperational for magnetic tape 

Access for read only 

Indicates file identifier pointer. Used to position a tape by file identifier. 

Indicates read attribute list (optional). 

Ignored. 

Access for read/write 

This function will be rejected with the error code IE.PRI. (Extend access is required.) 
Access for read/write/extend 

Indicates file identifier pointer. Used to position tape by file identifier. 

Indicates read attribute list (optional). 


Indicates AC.UPD (update mode). If AC.UPD is set, the tape will be positioned to 
overwrite the file and all files beyond the current file will be lost. If AC.UPD is not 
set, the tape will be positioned for append. If the file is not the last file, MTAACP 
returns the error code IE.ISQ. 


Deaccess file 
Indicates file identifier pointer is ignored. 


Indicates that the volume is to be rewound after the file is closed when AC.RWD is 
set. 


Read virtual block 
Indicates buffer address. 


Indicates buffer size. The buffer size must be greater than 18 bytes and less than 
the declared block length for the entire file. 


Indicates a high virtual block number (VBN). 
Indicates a low VBN. 


NOTE: The virtual block number must be either zero or exactly 
1 greater than the previous block number. 


Create File 


Function 


10.RAT 


10.APC 


Parameter 


#1 
#2 


#5 


#1 
#2 
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Meaning 


Indicates the file identifier pointer. The file sequence and section number will be 
returned to the user’s file identifier block. 


Indicates attribute list pointer. Used to write the attributes for the newly created file. 
Attribute type code must be positive. 


If AC.RWD is set, the volume will be positioned at the beginning and will overwrite 
the first file. This effectively reinitializes the volume. 


If AC.RWD is not set and AC.POS is set, the volume set will be positioned to the 
next file position beyond the current file and will overwrite that file. All files beyond 
that on the volume will be destroyed. 


If neither AC.RWD nor AC.POS is set, the volume set will be positioned at its end 
and the new file will be appended to the set. 


For unlabeled tapes, MTAACP only checks AC.RWD. 

Filename block pointer. 

Read Attributes 

Indicates the file identifier pointer. Used to position the tape by the file identifier. 
Indicates attribute list pointer (see Section H.3.2). 

The following attribute list entries are meaningful for magnetic tape: 


1,2 UIC 

1,4 UIC and protection 

1,5 UIC, protection, and characteristics 
2,2 Protection 

2,3 Protection and characteristics 

3,1 Characteristics 

4,32 User file attributes 

5,6 File name 


5,8 File name and type 

5,10 File name and type 

6,2 File type 

6,4 File type and version number 
7,2 Version number 

8,7 Expiration date 

-9,10 Statistics block (read only) 
-10,0 Entire header (read only) 
11,2 Block size 


ACP Control 
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Function Parameter Meaning 


#3 Indicates one of the following user control function codes: 


1 Rewind volume set. 

2 _— Position to end of volume set. 

3 Close current volume and continue processing the next 
section of the same file on the next volume of the volume 
set. 

4 Space physical records in currently accessed file. 

5 Get ACP characteristics. 

6 Rewind current file. 


10.APV Privileged ACP Control 


This function is used only by the MOUNT and DISMOUNT commands. This 
interface is subject to change and, therefore, will not be documented until a future 
release. 
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System Library Symbols 


Table I-1 describes the field size symbols that reside in the System Library (SYSLIB). These 
symbols are 


Table |-1 F 


Symbol 


S.BFHD 
S.FATT 
F.FDB 
F.FNAM 
S.FNB 
S.FNBW 
S.FNTY 
S.FSR2 
S.FTYP 
F.NFEN 


ize | Symbols 


global symbols that are resolved at task-build time through SYSLIB. 


leld Size Symbols 


Description 


Indicates the size of the file storage region (FSR) block buffer header in bytes. 


Indicates the size of the File Descriptor Block (FDB) file attribute area in bytes. 
Indicates the size of the FDB in bytes (including the name block). 

Indicates the size of the file name in bytes (stored in Radix-50 format). 

Indicates the size of the filename block (FNB) in bytes. 

Indicates the size of the filename block in words. 

Indicates the size of the file name and file type in words (stored in Radix-50 format). 
Indicates the size of the FSR2 (basic impure area). 

Indicates the size of the file type in bytes (stored in Radix-50 format). 

Indicates the size of a complete file name in bytes—file ID, name, type, and version. 
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The sample programs that follow read records from an input device, strip off any blanks to the 
right of the data portion of the record, and write the data record on an output device. While the 
programs are intended primarily for card reader input and printer output, device independence is 


maintained. 


Program CRCOPY 


The following example is the main program and is entitled CRCOPY. Sections J.2 and J.3 contain 
programs that are variations of CRCOPY (CRCOPA and CRCOPB). 


- TITLE 


° 
, 


-MCALL 
«-MCALL 
-MCALL 


INLUN=3 
OUTLUN=4 


FSRSZ$ 
FDBOUT: FDBDFS 
FDATSA 
FDRCSA 
FDOPSA 
FDBDFS$ 
FDRCSA 
FDOPSA 
RECBUF: .BLKB 
OFNAM: NMBLKS 
IFNAM: NMBLKS 
START: FINITS 
OPENSR 
BCS 
OPENSW 
BCS 
GTREC: GETS 
BCS 
MOV 
MOV 
ADD 
10S: CMPB 
BNE 
SOB 
7At this point, 


FDBIN: 


;record to be written. 
ja zero-length record is written. 


PTREC: PUTS 
BCC 
ERROR: NOP 


CRCOPY 


;Card reader copy routine 


FDBDFS$, FDATSA, FDRCSA, FDOPSA, NMBLKS , FSRSZ$ 
OPENSR, OPENSW, GETS, PUTS, CLOSES, EXITS$S 


FINITS 


2 


R.VAR, FD.CR 
, RECBUF, 80. 
OUTLUN, , OFNAM 


,RECBUF, 80. 
INLUN, , IFNAM 
80. 

OUTPUT, DAT 
INPUT, DAT 


#FDBIN 
ERROR 
#FDBOUT 
ERROR 
#FDBIN 
CKEOF 
F.NRBD (RO),R1 
#RECBUF, R2 
R1,R2 
#40,-(R2) 
PTREC 
R1,10$ 


7Assign CR or file device 
zAssign to output device 


;Allocate space for output FDB 
;Init file attributes 

zInit record attributes 

zInit file open section 
sAllocate space for input FDB 
sInit record attributes 

;Init file open section 
7;Record buffer 

;Output filename 

;Input filename 

sInit file storage region 
7;Open the input file 

7;Branch if error 

7Open the output file 

7Branch if error 

;Note - URBD is all set up 
;Error should be EOF indication 
7R1l=size of record read 


;R2=address of last bytet1l 
;Strip trailing blanks 


R1 contains the stripped size of the 


#FDBOUT, ,R1 
GTREC 


If the card is blank, 


7;R1 is needed to specify 
;the record size. 
;Error code goes here 
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CKEOF: CMPB #IE.EOF,F.ERR(RO) ;End of file? 
BNE ERROR ;Branch if other error 
CLOSES RO 7Close the input file 
BCS ERROR 
CLOSES #FDBOUT ;Close the output file 
BCS ERROR 
EXITSS Issue exit directive 
- END START 
Program CRCOPA 


The following sample program is entitled, CRCOPA. The CRCOPA program uses a data-set 
descriptor instead of the default filename block used in CRCOPY. 


«TITLE CRCOPA 7;Card reader copy routine 
-MCALL FDBDFS$,FDATSA, FDRCSA, FDOPSA, NMBLKS, FSRSZ$ 
-MCALL OPENSR, OPENSW, GETS, PUTS, CLOSES,EXITSS 
-MCALL FINITS 


INLUN=3 ;Assign CR or file device 
OUTLUN=4 sAssign to output device 
FSRSZ$ 2 


FDBOUT: FDBDFS 
FDATSA R.VAR,FD.CR 
FDRCSA_ ,RECBUF, 80. 
FDOPSA OUTLUN, OFDSPT 


'FDBIN: FDBDFS 


FDRCSA ,RECBUF, 80. 
FDOPSA INLUN, IFDSPT 
RECBUF: .BLKB 80. 


CFDSPT: .WORD 0,0 ;Device descriptor 
- WORD 0,0 Directory descriptor 
» WORD ONAMSZ,ONAM ;Filename descriptor 
IFDSPT: .WORD 0,0 ;Device descriptor 
- WORD 0,0 ;Directory descriptor 
- WORD INAMSZ, INAM ;Filename descriptor 
ONAM: -ASCII  /OUTPUT.DAT/ 
ONAMS Z=.-ONAM 
. EVEN 
INAM: «ASCII /INPUT.DAT/ 
INAMSZ=.-INAM 
. EVEN 
START: FINITS ;Init file storage region 
OPENSR #FDBIN ;Open the input file 
BCS ERROR ;Branch if error 
OPENSW #FDBOUT ;Open the output file 
BCS ERROR ;Branch if error 
GTREC: GETS #FDBIN ;Note - URBD is all set up 
BCS CKEOF ;Error should be EOF indication 
MOV F.NRBD(RO),R1 ;Rl=size of record read 
MOV #RECBUF, R2 
ADD R1,R2 ;R2=address of last bytetl 
10S: CMPB #40, -(R2) ;Strip trailing blanks 
BNE PTREC 
SOB R1,10$ 
*At this point, Rl contains the stripped size of the 
;xrecord to be written. If the card is blank, 


ja zero-length record is written. 
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PTREC: PUTS #FDBOUT, ,R1 7R1 is needed to specify 
Bcc GTREC ;the record size. 
ERROR: NOP ;Error code goes here 
CKEOF: CMPB #IE.EOF,F.ERR(RO) ;End of file? 
BNE ERROR ;Branch if other error 
CLOSES RO 7Close the input file 
BCS ERROR 
CLOSES #FDBOUT 7Close the output file 
BCS ERROR 
EXITSS j;Issue exit directive 


- END START 


Program CRCOPB 


The following program is entitled CRCOPB. The CRCOPB program uses run-time initialization of 
the File Descriptor Block (FDB). 


-TITLE CRCOPB 7Card reader copy routine 


e 
’ 


-MCALL FDBDFS$,FDATSA, FDRCSA, FDOPSA, NMBLKS , FSRSZ$ 
-MCALL OPENSR, OPENSW, GETS, PUTS, CLOSES, EXITSS 
-MCALL FINITS$,FDATSR 


INLUN=3 zAssign CR or file device 
OUTLUN=4 sAssign to output device 
FSRSZ$ 2 


FDBOUT: FDBDFS$ 
FDBIN: FDBDFS 
RECBUF: .BLKB 80. 


CFDSPT: .WORD 0,90 Device descriptor 
- WORD 0,0 ;Directory descriptor 
-WORD ONAMSZ,ONAM 7;Filename descriptor 
IFDSPT: .WORD 0,0 ;Device descriptor 
- WORD 0,0 ;Directory descriptor 
«WORD INAMSZ, INAM 7Filename descriptor 
ONAM: -ASCII /OUTPUT.DAT/ 
ONAMS Z= . -ONAM 
» EVEN 
INAM: -ASCII /INPUT.DAT/ 
INAMSZ= .-INAM 
- EVEN 
START: FINITS 7Init file storage region 


OPENSR #FDBIN, #INLUN, #IFDSPT, , #RECBUF, #80. 
7;Runtime initialization 


BcS ERROR Branch if error 
FDATSR #FDBOUT, #R.VAR, #FD.CR ;Runtime initialization 
OPENSW RO, #OUTLUN, #OFDSPT, , #RECBUF, #80. 
BCS ERROR *Branch if error 
GTREC: GETS #FDBIN ;Note - URBD is all set up 
BCS CKEOF ;Error should be EOF indication 
MOV F.NRBD(RO),R1 ;Rl=size of record read 
MOV #RECBUF, R2 
ADD R1,R2 7;R2=address of last byte+1 
108: CMPB #40,-(R2) ;Strip trailing blanks 
BNE PTREC 
SOB R1,10$ 
7At this point, R1 contains the stripped size of the 
yrecord to be written. If the card is blank, 


7a zero-length record is written. 
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PTREC: PUTS #FDBOUT,,R1 ;R1 is needed to specify 
BCC GTREC ;the record size. 
ERROR: NOP ;Error code goes here 
CKEOF: CMPB #IE.EOF,F.ERR(RO) ;End of file? 
BNE ERROR 7;Branch if other error 
CLOSES RO 7;Close the input file 
BCS ERROR 
CLOSES #FDBOUT 7Close the output file 
BCS ERROR 
EXITSS ;Issue exit directive 
- END START 


Error Codes 


This appendix includes the source code for the following: 
e I/O error codes 
¢ Directive Status Word (DSW) error codes 


e I/O function codes 


This source code is located in [61,10]QIOMAC.MAC and is listed as follows: 


- TITLE QIOMAC =- QIOSYM MACRO DEFINITION 


=e 


DATE OF LAST MODIFICATION: 


me Ye 


RYAN CHRISTOPHER 16-Nov-1984 


me 6M «6S Ne 


**x*e*k* ALWAYS UPDATE THE FOLLOWING TWO LINES TOGETHER 
- IDENT /0375/ 
QI. VER=0375 


COPYRIGHT (C) 1983, 1984 
DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS. 


THIS SOFTWARE IS FURNISHED UNDER A LICENSE FOR USE ONLY ON A 
SINGLE COMPUTER SYSTEM AND CAN BE COPIED ONLY WITH THE 
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE, OR 
ANY OTHER COPIES THEREOF, CAN NOT BE PROVIDED OR OTHERWISE 
MADE AVAILABLE TO ANY OTHER PERSON EXCEPT FOR USE ON SUCH 
SYSTEM AND TO ONE WHO AGREES TO THESE LICENSE TERMS. TITLE 
TO AND OWNERSHIP OF THE SOFTWARE SHALL AT ALL TIMES REMAIN 
IN DEC. 


we Ve we Vs Yo Ye Vo 


we Se Ye Ye Ye 


=e 


THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT 
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL 
EQUIPMENT CORPORATION. 


we 


=e Ss 


DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF 
ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC. 


oe Me Ne 


we 


SHANE MICHAEL 1-0CT-73 


+ 
MACRO TO DEFINE STANDARD QUEUE I/O DIRECTIVE FUNCTION VALUES 
AND IOSB RETURN VALUES. TO INVOKE AT ASSEMBLY TIME (WITH LOCAL 
DEFINITION) USE: 


se Ts Ve VW 


Qrosys 7;DEFINE SYMBOLS 


Se Ne Ye Ye Ne Ne 
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TO OBTAIN GLOBAL DEFINITION OF THESE SYMBOLS USE: 


QIOSY$ DEFS$G ;SYMBOLS DEFINED GLOBALLY 


“e ‘Ne Ss Ne 


THE MACRO CAN BE CALLED ONCE ONLY AND THEN 
REDEFINES ITSELF AS NULL. 


se “Ne Ne 


-MACRO QIOSYS $$S5GBL, $$SMSG 
-IIF IDN, <SS$GBL>,<DEFS$G>, .GLOBL QI.VER 


IF IDN, <SSSMSG>, <DEF$S> 

SSSMAX=0 

SSMSG=1 

.IFF 

$SSMSG=0 

-ENDC 

.MCALL TOERRS 

LOERRS $SSGBL 31/0 ERROR CODES FROM HANDLERS, FCP, FCS 
»-MCALL DRERRS$ 

DRERRS$ $$S$GBL ;DIRECTIVE STATUS WORD ERROR CODES 
IF DIF, <SS$S$MSG>, <DEFS$S> 

.-MCALL FILIOS 

FILIOS $SSGBL ;DEFINE GENERAL I/O FUNCTION CODES 
-MCALL SPCIOS 

SPCIOS $SSGBL ;DEVICE-DEPENDENT I/O FUNCTION CODES 
- MACRO Qrosys ARG, ARG1, ARG2 ;RECLAIM MACRO STORAGE 
. ENDM Qiosys$ 

.ENDC 


- ENDM QrIosys$ 


DEFINE THE ERROR CODES RETURNED BY DEVICE HANDLER AND FILE PRIMITIVES 
IN THE FIRST WORD OF THE I/O STATUS BLOCK 
THESE CODES ARE ALSO RETURNED BY FILE CONTROL SERVICES (FCS) IN THE 
BYTE F.ERR IN THE FILE DESCRIPTOR BLOCK (FDB) 
THE BYTE F.ERR+1 IS 0 IF F.ERR CONTAINS A HANDLER OR FCP ERROR CODE. 


™e Te Ne Ne Ne Ne Ne 


-ENABL LC 

. MACRO IOERRS S$SGBL 
-MCALL . IOER., DEFINS 

.IF IDN, <S$SGBL>, <DEF$G> 
...-GBL=1 

-IFF 

. «»-GBL=0 

- ENDC 

-IIF NDF, SSMSG, $$MSG=0 


we Ne Ne 


‘oe we Ne 


Error Codes 


SYSTEM STANDARD CODES, USED BY EXECUTIVE AND DRIVERS 


- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
-IOER. 
» IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- TOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- [OER. 
» IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 


TE.BAD, 
IE.IFC, 
TE.DNR, 
TE.VER, 
TE.ONP, 
IE.SPC, 
IE.DNA, 
LE.DAA, 
IE.DUN, 
TE.EOF, 
IE.EOV, 
TE.WLK, 
LE.DAO, 
LE.SRE, 
IE.ABO, 
IE.PRI, 
LE.RSU, 
LE.OVR, 
TE.BYT, 
IE.BLK, 
LE.MOD, 
IE.CON, 
IE.BBE, 
IE.STK, 
IE.FHE, 
IE.EOT, 
IE.OFL, 
IE.BCC, 
IE.NFW, 
IE.DIS, 
TE.PNT, 
IE.NDR, 
IE.TMO, 
LE.CNR, 
IE.MII, 
IE.SPI, 
IE.FER, 


FILE PRIMITIVE CODES 


- IOER. 
- IOER. 
- IOER. 
. IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
.- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 


IE.NOD, 
IE .DFU, 
IE.IFU, 
IE .NSF, 
TE.LCK, 
IE.HFU, 
LE.WAC, 
IE.CKS, 
TE.WAT, 
IE.RER, 
LE.WER, 
TE.ALN, 
LE.SNC, 
IE.SQc, 
IE.NLN, 
IE.CLO, 
TE.DUP, 
IE.BVR, 
IE.BHD, 
IE.EXP, 


-01.,<Bad parameters> 

-02.,<Invalid function code> 

-03.,<Device not ready> 

-04.,<Parity error on device> 

-05.,<Hardware option not present> 

-06.,<Illegal user buffer> 

-07.,<Device not attached> 

-08.,<Device already attached> 

-09.,<Device not attachable> 

-10.,<End of file detected> 

-11.,<End of volume detected> 

-12.,<Write attempted to locked unit> 

-13.,<Data overrun> 

-14.,<Send/receive failure> 

-15.,<Request terminated> 

-16.,<Privilege violation> 

-17.,<Shareable resource in use> 

-18.,<Illegal overlay request> 

-19.,<Odd byte count (or virtual address) > 
-20.,<Logical block number too large> 
-21.,<Invalid UDC module #> 

-22.,<UDC connect error> 

-56.,<Bad block on device> 

-58.,<Not enough stack space (FCS or FCP)> 
-59.,<Fatal hardware error on device> 

-62.,<End of tape detected> 

~65.,<Device off line> 

-66.,<Block check, CRC, or framing error> 
-69.,<Path lost to partner> ;THIS CODE MUST BE ODD 
-69.,<Path lost to partner> ;DISCONNECTED (SAME AS NFW) 
-71.,<Partition/Region not in system> 

-72.,<No dynamic space available> ; SEE ALSO IE.UPN 
~95.,<Timeout on request> 7 see also IS.TMO 
-96.,<Connection rejected> 

-99.,<Media inserted incorrectly> 

-100.,<Spindown ignored> 

-101.,<Forced error mark encountered> 


-23.,<Caller’s nodes exhausted> 
-24.,<Device full> 

-25.,<Index file full> 

-26.,<No such file> 

-27.,<Locked from read/write access> 
-28.,<File header full> 

-29.,<Accessed for write> 

-30.,<File header checksum failure> 
-31.,<Attribute control list format error> 
-32.,<File processor device read error> 
~33.,<File processor device write error> 
-34.,<File already accessed on LUN> 
-35.,<File ID, file number check> 
-36.,<File ID, sequence number check> 
-37.,<No file accessed on LUN> 

-38.,<File was not properly closed> 
-57.,<ENTER - duplicate entry in directory> 
-63.,<Bad version number> 

-64.,<Bad file header> 

-75.,<File expiration date not reached> 


K-3 


Error Codes 


™e we Ve 


“eo Ne Me 


Se Ne Ne 


“a Se Ne 
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- IOER. 
- IOER. 
. IOER. 
- IOER. 
- IOER. 
- IOER. 


IE.BTF,-76.,<Bad tape format> 

IE.ALC, -84.,<Allocation failure> 

IE.ULK, -85..,<Unlock error> 

IE.WCK, -86.,<Write check failure> 
IE.DSQ,-90.,<Disk quota exceeded> 
IE.PIO,-104.,<Deacess failed due to pending I/0> 


FILE CONTROL SERVICES CODES 


- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
. IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 


IE .NBF,-39.,<REFERENCE> (symbol) (OPEN - no buffer space available for f 


IE.RBG, -40.,<REFERENCE> (symbol) (Illegal record size) 


IE.NBK, -41.,<REFERENCE> (symbol) (File exceeds space allocated, no block 
IE.ILL, -42.,<REFERENCE> (symbol) (Illegal operation on file descriptor fk 


IE.BTP, -43.,<REFERENCE> (symbol) (Bad record type) 
IE.RAC, -44.,<REFERENCE> (symbol) (Illegal record access bits set) 


IE.RAT, -45.,<REFERENCE> (symbol) (Illegal record attributes bits set) 
IE.RCN, -46.,<REFERENCE> (symbol) (Illegal record number - too large) 


IE.2DV, -48., <REFERENCE> (symbol) (Rename - 2 different devices) 


IE.FEX, -49., <REFERENCE> (symbol) (Rename - new file name already in use) 


IE.BDR, -50., <REFERENCE> (symbol) (Bad directory file) 

IE.RNM, -51., <REFERENCE> (symbol) (Can’t rename old file system) 
IE.BDI, -52.,<REFERENCE> (symbol) (Bad directory syntax) 

IE.FOP, -53.,<REFERENCE> (symbol) (File already open) 

IE.BNM, -54.,<REFERENCE> (symbol) (Bad file name) 

IE.BDV,-55., <REFERENCE> (symbol) (Bad device name) 
IE.NFI,-60.,<REFERENCE> (symbol) (File ID was not specified) 
IE.ISQ,-61.,<REFERENCE> (symbol) (Illegal sequential operation) 
IE.NNC,-77.,<REFERENCE> (symbol) (Not ANSI 'D’ format byte count) 


NETWORK ACP, PSI, AND DECDATAWAY CODES 


- LOER. 
- IOER. 
- IOER. 
. IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 
- IOER. 


ICS/ICR ERROR 
- IOER. 


- IOER. 
- IOER. 


IE.NNN,-68.,<No such node> 

IE.BLB,-70.,<Bad logical buffer> 
IE.URJ,~-73.,<Connection rejected by user> 
IE.NRJ,-74.,<Connection rejected by network> 
IE.NDA,-78.,<No data available> 
IE.IQU,-91.,<Inconsistent qualifier usage> 
IE.RES, -92.,<Circuit reset during operation> 
IE.TML,-93.,<Too many links to task> 
IE.NNT,-94.,<Not a network task> 

IE.UKN, -97.,<Unknown name> 
IE.IRR,-102.,<Insufficient resources at remote node> 
IE.SIU,-103.,<Service in use> 


CODES 
IE.NLK,-79.,<Task not linked to specified ICS/ICR interrupts> 


IE.NST,-80.,<Specified task not installed> 
IE.FLN,-81.,<Device offline when offline request was issued> 


TTY ERROR CODES 


- IOER. 
- IOER. 


IE.IES,-82.,<Invalid escape sequence> 
IE.PES,-83.,<Partial escape sequence> 


RECONFIGURATION CODES 


- IOER. 
- IOER. 
- IOER. 


IE.ICE,-47.,<Internal consistancy error> 
IE.ONL, -67.,<Device online> 
IE.SZE,-98.,<Unable to size device> 


PCL ERROR CODES 
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- IOER. 
- IOER. 
- IOER. 


SUCCESSFUL RETURN CODES--- 


DEFIN$ IS.PND,+00. 
DEFINS$ IS.SUC,+01. 
DEFIN$ IS.RDD,+02. 
DEFINS IS.TNC,+02. 
DEFINS IS.CHW,+04. 
DEFINS IS.BV,+05. 
DEFINS$ IS.DAO,+02. 

TTY SUCCESS CODES 
DEFINS IS.CR,<15*400+1> 
DEFINS$ IS.ESC,<33*400+1> 
DEFINS IS.CC,<3*400+1> 
DEFIN$ IS.ESQ,<233*400+1> 
DEFINS IS.PES,<200*400+1> 
DEFINS IS.EOT,<4*400+1> 
DEFIN$ IS.TAB,<11*400+1> 
DEFIN$ IS.TMO,+2. 
DEFINS$ IS.00B,+3. 
DEFINS IS.TMM,+4. 


Error Codes 


IE.NTR,-87.,<Task not triggered> 
IE.REJ,-88.,<Transfer rejected by receiving CPU> 
IE.FLG,-89.,<Event flag already specified> 


7;OPERATION PENDING 


7OPERATION COMPLETE, 


SUCCESS 


7FLOPPY DISK SUCCESSFUL COMPLETION 


7;OF A READ PHYSICAL, 


AND DELETED 


;DATA MARK WAS SEEN IN SECTOR HEADER 

7 (PCL) SUCCESSFUL TRANSFER BUT MESSAGE 
;TRUNCATED (RECEIVE BUFFER TOO SMALL). 
; (IBM COMM) DATA READ WAS RESULT OF 
7I1BM HOST CHAINED WRITE OPERATION 

; (A/D READ) AT LEAST ONE BAD VALUE 
7;WAS READ (REMAINDER MIGHT BE GOOD). 
7BAD CHANNEL IS INDICATED BY A 
;NEGATIVE VALUE IN THE BUFFER. 

7; SUCCESSFUL BUT WITH DATA OVERRUN 

7 (NOT TO BE CONFUSED WITH IE.DAO) 


;CARRIAGE RETURN WAS TERMINATOR 

7ESCAPE (ALTMODE) WAS TERMINATOR 
;CONTROL-C WAS TERMINATOR 

;ESCAPE SEQUENCE WAS TERMINATOR 
7;PARTIAL ESCAPE SEQUENCE WAS TERMINATOR 
;EOT WAS TERMINATOR (BLOCK MODE INPUT) 
7TAB WAS TERMINATOR (FORMS MODE INPUT) 


7;REQUEST TIMED OUT 
;OUT OF BAND TERMINATOR (TERM IN HIGH BYTE) 


;READ COMPLETED, 


Professional Bisync Success Codes 


DEFINS IS.RVI,+2. 
DEFINS IS.CNV, +3. 
DEF INS IS.XPT,+5. 


e 
’ 
e 
c 
e 
cd 


DATA SUCC. XMITTED; 
DATA SUCC. XMITTED; 


MANAGEMENT MODE SEQ RCVD 


HOST ACKED W/RVI 
HOST ACKED W/CONVERSATION 


DATA SUCC. RECVD IN TRANSPARENT MODE 


Professional Bisync Abort Codes 


These codes are returned in the high byte of the first word of the IOSB 
when the low byte contains IE.ABO. 


DEFINS SB.KIL,-1. 
DEFINS SB.ACK,-2. 
DEFINS SB.NAK, -3. 
DEFINS SB.ENQ, -4. 
DEF INS SB.BOF,-5. 
DEFINS SB.TMO,-6. 
DEFINS SB.DIS,-7. 


KKKKKK 


KeKKKK 


-IF 

-MACRO 
- ENDM 
»ENDC 
- ENDM 


THE NEXT AVAILABLE ERROR 


EQ, $$MSG 
IOERRS A 
IOERRS 


IOERRS$ 


=e 


se Ys Ne Ne Se Ne 


ABORTED 
ABORTED 
ABORTED 
ABORTED 
ABORTED 
ABORTED 
ABORTED 


NUMBER IS: 


BY IO.KIL 


BECAUSE 
BECAUSE 
BECAUSE 
BECAUSE 
BECAUSE 
BECAUSE 


-101. 


TOO MANY ACKS RECD OUT OF SEQ 
NAK THRESHOLD EXCEEDED 

ENQ THRESHOLD EXCEEDED 

OF IO.RLB BUFFER OVERFLOW 

OF TIMEOUT 


HOST DISCONNECTED W/ DLE, EOT 


Error Codes 


; DEFINE THE DIRECTIVE ERROR CODES RETURNED IN THE DIRECTIVE STATUS WORD 


; FILE CONTROL SERVICES (FCS) RETURNS THESE CODES IN THE BYTE F.ERR 
; OF THE FILE DESCRIPTOR BLOCK (FDB). TO DISTINGUISH THEM FROM THE 
7; OVERLAPPING CODES FROM HANDLER AND FILE PRIMITIVES, THE BYTE 

; F.ERR+1 IN THE FDB WILL BE NEGATIVE FOR A DIRECTIVE ERROR CODE. 


. MACRO DRERRS SSSGBL 

»MCALL -QIOE., DEFINS 

IF IDN, <SSSGBL>, <DEFS$G> 
. GBL=1 

.IFF 

. . GBL=0 

»ENDC 

-IIF NDF, $SMSG, $SMSG=0 


STANDARD ERROR CODES RETURNED BY DIRECTIVES IN THE DIRECTIVE STATUS WORD 


“eae Ne Te 


-QIOE. IE.UPN,-01.,<Insufficient dynamic storage> ; SEE ALSO IE.NDR 
-QIOE. IE.INS,-02.,<Specified task not installed> 

-QIOE. IE.PTS,-03.,<Partition too small for task> 

-QIOE. IE.UNS,-04.,<Insufficient dynamic storage for send> 
-QIOE. IE.ULN, -05.,<Un-assigned LUN> 

-QIOE. IE.HWR,-06.,<Device handler not resident> 

-QIOE. IE.ACT,-07.,<Task not active> 

-QIOE. IE.ITS,-08.,<Directive inconsistent with task state> 
-QIOE. IE.FIX,-09.,<Task already fixed/unfixed> 

-QIOE. IE.CKP,-10.,<Issuing task not checkpointable> 
-QIOE. IE.TCH,-11.,<Task is checkpointable> 

-QIOE. IE.RBS,-15.,<Receive buffer is too small> 

-QIOE. IE.PRI,-16.,<Privilege violation> 

-QIOE. IE.RSU,-17.,<Resource in use> 

-QIOE. IE.NSW,-18.,<No swap space available> 

-QIOE. IE.ILV,-19.,<Illegal vector specified> 

-QIOE. IE.ITN, -20.,<Invalid table number> 

-QIOE. IE.LNF, -21.,<Logical name not found> 

-QIOE. IE.AST,-80.,<Directive issued/not issued from AST> 
-QIOE. IE.MAP,-81.,<Illegal mapping specified> 

-QIOE. IE.IOP,-83.,<Window has I/O in progress> 

-QIOE. IE.ALG, -84.,<Alignment error> 

-QIOE. IE.WOV, -85.,<Address window allocation overflow> 
-QIOE. IE.NVR, -86.,<Invalid region ID> 

-QIOE. IE.NVW,-87.,<Invalid address window ID> 

-QIOE. IE.ITP,-88.,<Invalid TI parameter> 

~-QIOE. IE.IBS,-89.,<Invalid send buffer size ( .GT. 255.)> 
~-QIOE. IE.LNL,-90.,<LUN locked in use> 

-QIOE. IE.IUI,-91.,<Invalid UIC> 

-QIOE. IE.IDU, -92.,<Invalid device or unit> 

-QIOE. IE.ITI,-93.,<Invalid time parameters> 

-QIOE. IE.PNS,-94.,<Partition/region not in system> 

-QIOE. IE.IPR,-95.,<Invalid priority ( .GT. 250.)> 

-QIOE. IE. ILU,-96.,<Invalid LUN> 

-QIOE. IE.IEF,-97.,<Invalid event flag ( .GT. 64.)> 

-QIOE. IE.ADP,-98.,<Part of DPB out of user’s space> 
-QIOE. IE.SDP,-99.,<DIC or DPB size invalid> 


7 SUCCESS CODES FROM DIRECTIVES - PLACED IN THE DIRECTIVE STATUS WORD 
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DEFINS 
DEF INS 
DEF INS 
DEF INS 


DEF INS 


IF 
-MACRO 
- ENDM 
- ENDC 
- ENDM 


IS.CLR,0 
IS.SET,2 
IS.SPD,2 
IS.SUP,3 


IS.WAT, 4 


EQ, $$MSG 
DRERR$ A 
DRERR$ 


DRERRS 


Error Codes 


;EVENT FLAG WAS CLEAR 

7;FROM CLEAR EVENT FLAG DIRECTIVE 
7EVENT FLAG WAS SET 

7FROM SET EVENT FLAG DIRECTIVE 
7TASK WAS SUSPENDED 


LOGICAL NAME SUPERSEDED 


Ne Se Ne Ne Ne 


OPERATION INITIATED, WAIT FOR COMPLETION 
FROM "VAX-11 IAS" RMS-21 ELEP$ DIRECTIVE 


DEFINE THE GENERAL I/O FUNCTION CODES - DEVICE INDEPENDENT 


- MACRO 


-MCALL 


IF 
-IFF 


-. -GBL=0 


- ENDC 


FILIOS S$SSGBL 
-WORD.,DEFINS 


IDN, <SS$GBL>, <DEF$G> 


GENERAL I/O QUALIFIER BYTE DEFINITIONS 


-WORD. 
-WORD. 
-WORD. 
- WORD. 
-WORD. 


IQ.X, 001,000 
1Q.Q,002, 000 
IQ.S,004,000 
IQ.UMD, 004,000 
IQ.LCK, 200,000 


EXPRESS QUEUE COMMANDS 


-WORD. 
-WORD. 
-WORD. 
- WORD. 
-WORD. 
- WORD. 


I0.KIL, 012,000 
IO.RDN, 022,000 
I0.UNL, 042,000 
IO.LTK, 050,000 
IO.RTK, 060, 000 
I0.SET, 030,000 


GENERAL DEVICE DRIVER CODES 


-WORD. 
»WORD. 
-WORD. 
»WORD. 
.-WORD. 
-WORD. 


IO.WLB, 000,001 
IO.RLB, 000, 002 
IO.LOV, 010,002 
IO.LDO, 110, 002 
IO.ATT, 000,003 
IO.DET, 000,004 


DIRECTORY PRIMITIVE CODES 


-WORD. 
-WORD. 
-WORD. 


IO.FNA, 000,011 
IO.RNA, 000,013 
IO.ENA, 000,014 


7;NO ERROR RECOVERY 

7;QUEUE REQUEST IN EXPRESS QUEUE 
7;SYNONYM FOR IQ.UMD 

;USER MODE DIAGNOSTIC STATUS REQUIRED 
;MODIFY IMPLIED LOCK FUNCTION 


7KILL CURRENT REQUEST 

71/0 RUNDOWN 

;UNLOAD I/O HANDLER TASK 
7LOAD A TASK IMAGE FILE 
;RECORD A TASK IMAGE FILE 
;SET CHARACTERISTICS FUNCTION 


7;WRITE LOGICAL BLOCK 

READ LOGICAL BLOCK 

7LOAD OVERLAY (DISK DRIVER) 
7;LOAD D-SPACE OVERLAY (DISK) 
7;ATTACH A DEVICE TO A TASK 
;DETACH A DEVICE FROM A TASK 


;FIND FILE NAME IN DIRECTORY 
7REMOVE FILE NAME FROM DIRECTORY 
7ENTER FILE NAME IN DIRECTORY 


Error Codes 


FILE PRIMITIVE CODES 


“=e “Ne Te 


-WORD. IO.CLN, 000,007 ;CLOSE OUT LUN 

.»WORD. I0.ULK, 000,012 ; UNLOCK BLOCK 

-WORD. IO.ACR, 000,015 7;ACCESS FOR READ 
-WORD. I0.ACW, 000,016 ;ACCESS FOR WRITE 
»WORD. IO.ACE,000,017 7;ACCESS FOR EXTEND 
-WORD. IO .DAC, 000,020 7DE-ACCESS FILE 

- WORD. IO.RVB, 000,021 ;READ VIRITUAL BLOCK 
-WORD. IO.WVB, 000,022 ;WRITE VIRITUAL BLOCK 
- WORD. I0.EXT, 000,023 ;EXTEND FILE 

-WORD. I0.CRE, 000,024 ;CREATE FILE 

-WORD. I0.DEL,000,025 7;DELETE FILE 

» WORD. IO.RAT, 000,026 7;READ FILE ATTRIBUTES 
-WORD. IO.WAT, 000,027 7;WRITE FILE ATTRIBUTES 
-WORD. IO.APV, 010,030 7;PRIVILEGED ACP CONTROL 
-WORD. IO. APC, 000,030 7ACP CONTROL 


=e Ne 


- MACRO FILIOS A 
- ENDM FILIOS 
» ENDM FILIO$S 


me 


DEFINE THE I/O FUNCTION CODES THAT ARE SPECIFIC TO INDIVIDUAL DEVICES 


“se Se 


- MACRO SPCIOS S$SSGBL 
-MCALL .WORD. , DEF INS 

IF IDN, <S$$GBL>, <DEFSG> 
..-GBL=1 

. IFF 

. » -GBL=0 

-ENDC 


I/O FUNCTION CODES FOR SPECIFIC DEVICE-DEPENDENT FUNCTIONS 


we Ne Ne 


.WORD. IO.WLV,100,001 ;(DECTAPE) WRITE LOGICAL REVERSE 
.WORD. IO.WLS,010,001 ;(COMM.) WRITE PRECEDED BY SYNC TRAIN 

WORD. IO.WNS,020,001 ;(COMM.) WRITE, NO SYNC TRAIN 

-WORD. IO.WAL,010,001 ;(TTY) WRITE PASSING ALL CHARACTERS 

.WORD. I0.WMS,020,001 ; (TTY) WRITE SUPPRESSIBLE MESSAGE 

WORD. I0.CCO,040,001 ;(TTY) WRITE WITH CANCEL CONTROL-O 

.WORD. IO.WBT,100,001 ; (TTY) WRITE WITH BREAKTHROUGH 

.WORD. IO.WLT,010,001 ; (DISK) WRITE LAST TRACK 

.WORD. IO.WLC,020,001 ; (DISK) WRITE LOGICAL W/ WRITECHECK 

.WORD. IO.WPB,040,001 ; (DISK) WRITE PHYSICAL BLOCK 

WORD. IO.WDD,140,001 ; (FLOPPY DISK) WRITE PHYSICAL W/ DELETED DATA 


-WORD. IO.RSN,140,002 ;(MSCP DISK) READ VOLUME SERIAL NUMBER 
-WORD. IO.RLV,100,002 ; (MAGTAPE,DECTAPE) READ REVERSE 

WORD. IO.RST,001,002 ; (TTY) READ WITH SPECIAL TERMINATOR 
-WORD. IO.RAL,010,002 ; (TTY) READ PASSING ALL CHARACTERS 
«WORD. IO.RNE,020,002 ; (TTY) READ WITHOUT ECHO 

- WORD. IO.RNC,040,002 ; (TTY) READ - NO LOWERCASE CONVERT 
-WORD. IO.RTM,200,002 ; (TTY) READ WITH TIME-OUT 

»WORD. IO.RDB,200,002 ; (CARD READER) READ BINARY MODE 

«WORD. IO0.SCF,200,002 ; (DISK) SHADOW COPY FUNCTION 

»WORD. IO.RHD,010,002 ;(COMM.) READ, STRIP SYNC 


»~WORD. 
»WORD. 
-WORD. 
~WORD. 
-WORD. 
-WORD. 
-WORD. 
~WORD. 
~WORD. 
»WORD. 
~WORD. 
~WORD. 
~WORD. 
»WORD. 
»WORD. 
»~WORD. 
~WORD. 
»WORD. 
~WORD. 
»WORD. 
-WORD. 
»WORD. 
»WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
»-WORD. 
»WORD. 
-WORD. 
-WORD. 
»WORD. 
-WORD. 
»WORD. 
»WORD. 
~WORD. 
~WORD. 
-WORD. 
»WORD. 
»WORD. 
-WORD. 
-WORD. 
-WORD. 
«WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
»WORD. 


IO.RNS, 020,002 
IO.CRC, 040, 002 
IO.RPB, 040, 002 
IO.RDF, 240, 002 
IO.RLC, 020, 002 
IO.ATA,010,003 
I0.GTS,000,005 
IO.R1C, 000,005 
IO. INL, 000,005 
I0.TRM, 010,005 
IO.RWD,000,005 
I0.SPB,020,005 
IO.RPL,020,005 
IO.SPF,040,005 
I0.STC, 100,005 
IO.SMD, 110,005 
I0.SEC, 120,005 
IO.RWU, 140,005 
I0.SMO, 160,005 
IO.HNG, 000, 006 
IO.HLD, 100, 006 
I0.BRK, 200, 006 
IO.RBC, 000, 006 
IO.MOD, 000, 006 
IO .HDX, 010,006 
I0.FDX, 020, 006 
IO.SYN, 040, 006 
I0.EOF, 000, 006 
IO.ERS, 020, 006 
IO.DSE, 040, 006 
IO.RTC, 000,007 
IO.SAO,000,010 
I0.SSO,000,011 
IO.RPR,000,011 
IO.MSO, 000, 012 
IO.RTT, 001,012 
I0.SLO,000,013 
IO.MLO, 000,014 
IO.LED,000,024 
I0.SDO0,000,025 
IO.SDI,000, 026 
IO.SCS, 000,026 
IO.REL, 000,027 
IO.MCS, 000, 027 
I0.ADS, 000,030 
I0.CCI, 000,030 
I0.LOD, 000, 030 
IO.MDI,000,031 
I0.DCI, 000,031 
IO.PAD, 000,031 
HT .RPP, 010,000 


Error Codes 


7 (COMM.) READ, DON’T STRIP SYNC 

7 (COMM.) READ, DON’T CLEAR CRC 

; (DISK) READ PHYSICAL BLOCK 

7; (DISK) READ DISK FORMAT 

; (DISK,MAGTAPE) READ LOGICAL W/ READCHECK 
7 (TTY) ATTACH WITH ASTS 

; (TTY) GET TERMINAL SUPPORT CHARACTERISTICS 
7; (AFC,ADO1,UDC) READ SINGLE CHANNEL 

7; (COMM.) INITIALIZATION FUNCTION 

7 (COMM.) TERMINATION FUNCTION 

7 (MAGTAPE, DECTAPE) REWIND 

7 (MAGTAPE) SPACE "N" BLOCKS 

7; (DISK) REPLACE LOGICAL BLOCK (RESECTOR) 
7; (MAGTAPE) SPACE "N" EOF MARKS 

7;SET CHARACTERISTIC 

3 (FLOPPY DISK) SET MEDIA DENSITY 
7SENSE CHARACTERISTIC 

; (MAGTAPE, DECTAPE) REWIND AND UNLOAD 

7 (MAGTAPE) MOUNT & SET CHARACTERISTICS 
7; (TTY) HANGUP DIAL-UP LINE 

3; (TMS) HANGUP BUT LEAVE LINE ON HOLD 

; (PRO/TTY) SEND SHORT OR LONG BREAK 
;READ MULTICHANNELS (BUFFER DEFINES CHANNELS) 
3; (COMM.) SETMODE FUNCTION FAMILY 

7 (COMM.) SET UNIT HALF DUPLEX 

7 (COMM.) SET UNIT FULL DUPLEX 

7 (COMM.) SPECIFY SYNC CHARACTER 

7; (MAGTAPE) WRITE EOF 

7 (MAGTAPE) ERASE TAPE 

7 (MAGTAPE) DATA SECURITY ERASE 

7READ CHANNEL - TIME BASED 

7 (UDC) SINGLE CHANNEL ANALOG OUTPUT 

7 (UDC) SINGLE SHOT, SINGLE POINT 

7 (TTY) READ WITH PROMPT 

7 (UDC) SINGLE SHOT, MULTI-POINT 

; (TTY) READ WITH TERMINATOR TABLE 

7; (UDC) LATCHING, SINGLE POINT 

7 (UDC) LATCHING, MULTI-POINT 

7 (LPS11) WRITE LED DISPLAY LIGHTS 

; (LPS11) WRITE DIGITAL OUTPUT REGISTER 
7 (LPS11) READ DIGITAL INPUT REGISTER 

7 (UDC) CONTACT SENSE, SINGLE POINT 

7; (LPS11) WRITE RELAY 

7 (UDC) CONTACT SENSE, MULTI-POINT 

; (LPS11) SYNCHRONOUS A/D SAMPLING 

7 (UDC) CONTACT INT - CONNECT 

7 (LPA11) LOAD MICROCODE 

7 (LPS11) SYNCHRONOUS DIGITAL INPUT 

7; (UDC) CONTACT INT ~- DISCONNECT 

7 (PSI) DIRECT CONTROL OF X.29 PAD 

+ (PSI) RESET PAD PARAMETERS SUBFUNCTION 


Error Codes 


-WORD. 
-WORD. 
-WORD. 
-WORD. 
»WORD. 
- WORD. 
-WORD. 
- WORD. 
-WORD. 
- WORD. 
-WORD. 


-WORD. 
~WORD. 
»WORD. 


-WORD. 
-WORD. 


-WORD. 
.WORD. 
-WORD. 
-WORD. 
-WORD. 


-WORD. 
-WORD. 


»WORD. 


we Ne Ne 


- WORD. 


se “Me Ne Oe 


.WORD. 
. WORD. 
DEFINS 
DEFINS 


=e te Ne 


-WORD. 
-WORD. 
»WORD. 
»WORD. 
-WORD. 
-WORD. 
«WORD. 


IO.XMT, 000,031 
IO.XNA, 010,031 
IO. INI,000,031 
IO.HIS, 000, 032 
IO.RCI, 000, 032 
IO.RCV, 000, 032 
I0.CLK, 000, 032 
IO0.CSR, 000, 032 
IO.MDO, 000, 033 
I0.CTI,000,033 
IO0.CON, 000,033 


IO0.ORG, 010,033 
IO.ANS, 020,033 
IO0.STA, 000,033 


I0.DTI,000,034 
I0.DIS, 000, 034 


IO.MDA, 000,034 
IO.DPT,010,034 
IO.RTI,000,035 
I0.CTL, 000,035 
IO0.STP,000,035 


I0.SWI,000,035 
IO.CNT, 000,036 


IO0.ITI,000,036 


EXTENDED I/O FUNCTION 


I0.EIO, 000,037 


IO.RSD, 030,014 
IO.WSD, 010,013 
SD.TXT,0 
SD.GDS,1 


PROFESSIONAL 300 BISYNC DRIVER 


SB.PRT, 020,003 
SB.CLR, 010,036 
SB.RDY, 010,033 
SB.NRD, 020,033 
IO.LBK, 000, 035 
SB.CBL, 010,035 
SB.CLK, 020,035 
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PRO 300 SERIES BITMAP FUNCTIONS 


NOTE: THESE FUNCTIONS ARE FOR 


“eae “ae Ne Ne 


“e 


Ne Nt Ne Ne Ne Ne 


TRANSMIT SPECIFIED BLOCK WITH ACK 
TRANSMIT WITHOUT ACK 

(LPA11) INITIALIZE 

(LPS11) SYNCHRONOUS HISTOGRAM SAMPLING 
(UDC) CONTACT INT - READ 

(COMM.) RECEIVE DATA IN BUFFER SPECIFIED 
(LPA11) START CLOCK 

(BUS SWITCH) READ CSR REGISTER 

(LPS11) SYNCHRONOUS DIGITAL OUTPUT 

(UDC) TIMER - CONNECT 

(COMM.) CONNECT FUNCTION 

(VT11) - CONNECT TASK TO DISPLAY PROCESSOR 
(BUS SWITCH) CONNECT TO SPECIFIED BUS 
(COMM./PRO) DIAL TELEPHONE AND ORIGINATE 
(COMM.) INITIATE CONNECTION IN ORIGINATE MODE 
(COMM.) INITIATE CONNECTION IN ANSWER MODE 
(LPA11) START DATA TRANSFER 

(XJDRV) - SHOW STATE 

(UDC) TIMER - DISCONNECT 

(COMM.) DISCONNECT FUNCTION 

(VT11) - DISCONNECT TASK FROM DISPLAY PROCESSOR 
(BUS SWITCH) SWITCHED BUS DISCONNECT 
(LPS11) SYNCHRONOUS D/A OUTPUT 

(BUS SWITCH) DISCONNECT TO SPECIF PORT NO. 
(UDC) TIMER - READ 

(COMM.) NETWORK CONTROL FUNCTION 
(LPS11,LPA11) STOP IN PROGRESS FUNCTION 
(VT11) - STOP DISPLAY PROCESSOR 

(BUS SWITCH) SWITCH BUSSES 

(VT11) - CONTINUE DISPLAY PROCESSOR 
(XJDRV) - SHOW COUNTERS 

(UDC) TIMER - INITIALIZE 


(COMM. ) 
(COMM. ) 


(TTY) TSA EXTENDED I/0 


DEC USE ONLY AND ARE SUBJECT TO CHANGE 


READ SPECIAL DATA 

WRITE SPECIAL DATA 

TEXT DATA TYPE FOR SPECIAL DATA 
GIDIS DATA TYPE FOR SPECIAL DATA 


(XJDRV) FUNCTIONS 


ATTACH AS A PRINTER 

CLEAR COUNTERS (IO.CNT SUBFUNCTION) 

SET DEVICE STATE READY (IO.STA SUBFUNC) 
SET DEVICE STATE NOT READY 

PERFORM LOOPBACK TEST 

PERFORM CABLE LOOPBACK TEST 

DEVICE PERFORMS LINE CLOCKING 


se we Me 


™s ‘Ne Ye 
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COMMUNICATIONS FUNCTIONS 


. WORD. IO.CPR,010,033 
WORD. I0.CAS,020,033 
- WORD. I0.CRJ,040,033 
-WORD. I0.CBO, 110,033 
- WORD. I0.CTR, 210,033 


- WORD. IO0.GNI,010,035 
- WORD. I0.GLI,020,035 
- WORD. I0.GLC, 030,035 
- WORD. IO0.GRI,040,035 
-WORD. IO.GRC, 050,035 
-WORD. IO0.GRN, 060,035 


» WORD. IO .CSM, 070,035 
»WORD. IO.CIN, 100,035 
» WORD. IO0.SPW,110,035 
- WORD. I0.CPW,120,035 
- WORD. IO.NLB, 130,035 
-WORD. IO.DLB, 140,035 


ICS/ICR I/O FUNCTIONS 


IP11 


.WORD.  I0.CTY,000,007 
.WORD.  IO.DTY,000,015 
.WORD. IO.LDI,000,016 
-WORD. I0.UDI,010,023 


.WORD. I0.LTI,000,017 
.WORD. I0.UTI,020,023 
-WORD. I0.LTY,000,020 


.WORD. I0.UTY,030,023 
WORD. I0O.LKE,000,024 
WORD. IO.UER,040,023 
-WORD. IO.NLK,000,023 
-WORD. IO.ONL,000,037 
-WORD. I0O.FLN, 000,025 
WORD. IO.RAD,000,021 


I/O FUNCTIONS 


- WORD. IO.MAO, 010,007 
-WORD. IO.LEI,010,017 
-WORD. IO.RDD,010,020 
-WORD. IO.RMT,020,020 
-WORD. I0.LSTI,000,022 
-WORD. IO.UEI,050,023 
-WORD. I0.USI,060,023 
-WORD. I0.CSI,000,026 
-WORD. IO0.DSI,000,027 
-WORD. IO0.RAM, 000, 032 
-WORD. IO.RLK, 000,013 
-WORD. IO.EBT,000,011 


Error Codes 


7; CONNECT NO TIME-OUTS 
;CONNECT WITH AST 

7;CONNECT REJECT 

;BOOT CONNECT 

; TRANSPARENT CONNECT 

7;GET NODE INFORMATION 

7GET LINK INFORMATION 

7GET LINK INFO CLEAR COUNTERS 
7;GET REMOTE NODE INFORMATION 
7;GET REMOTE NODE ERROR COUNTS 
7;GET REMOTE NODE NAME 

;CHANGE SOLO MODE 

7;CHANGE CONNECTION INHIBIT 
;SPECIFY NETWORK PASSWORD 
7CHECK NETWORK PASSWORD 

7;NSP LOOPBACK 

;DDCMP LOOPBACK 


7;CONNECT TO TERMINAL INTERRUPTS 
7;DISCONNECT FROM TERMINAL INTERRUPTS 
7;LINK TO DIGITAL INTERRUPTS 

;UNLINK FROM DIGITAL INTERRUPTS 

7;LINK TO COUNTER MODULE INTERRUPTS 

7; UNLINK FROM COUNTER MODULE INTERRUPTS 
7;LINK TO REMOTE TERMINAL INTERRUPTS 
;UNLINK FROM REMOTE TERMINAL INTERRUPTS 
7;LINK TO ERROR INTERRUPTS 

7; UNLINK FROM ERROR INTERRUPTS 

;UNLINK FROM ALL INTERRUPTS 

;UNIT ONLINE 

;UNIT OFFLINE 

7;READ ACTIVATING DATA 


;MULTIPLE ANALOG OUTPUTS 

;LINK EVENT FLAGS TO INTERRUPT 
;READ DIGITAL DATA 

;READ MAPPING TABLE 

7;LINK TO DSI INTERRUPTS 
;UNLINK EVENT FLAGS 

;UNLINK FROM DSI INTERRUPTS 
7;CONNECT TO DSI INTERRUPTS 
;DISCONNECT FROM DSI INTERRUPTS 
;READ ANALOG MAPPING TABLES 
;READ RESOURCE LINKAGES 

;CHECK EBIT STATUS 


K-11 


Error Codes 


se Ne Ne 


- WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
- MACRO 
- ENDM 

- ENDM 


“ee “Ne we Ne 


- MACRO 

-MCALL 

-IF IDN 
--.-GBL=1 

. IFF 
..-GBL=0 

- ENDC 


we Ne Me 


-WORD. 


~e Ne ON 


» WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
.-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
»WORD. 
» WORD. 
-WORD. 
»WORD. 


we Ne Ne 


» MACRO 
- ENDM 


PCL11 I/O FUNCTIONS 


IO.ATX,000,001 
IO.ATF,000, 002 
IO.CRX, 000,031 
IO .DRX, 000, 032 
IO.RTF, 000, 033 
SPCIOS A 
SPCIOS 

SPCIOS 


DEFINE THE I/O CODES FOR USER-MODE DIAGNOSTICS. 
FUNCTIONS ARE IMPLEMENTED AS A SUBFUNCTION OF I/O CODE 10 (OCTAL). 


UMDIO$ 
-WORD. , DEFINS 


<$$$GBL>, <DEF$G> 


IQ.UMD, 004,000 


IO0.HMS,000,010 
I0.BLS,010,010 
IO.OFF,020,010 
IO.RDH, 030,010 
IO.WDH, 040,010 
IO.WCK, 050,010 
IO0.RNF,060,010 
IO.RNR, 070,010 
IO.LPC,100,010 
IO.RTD,120,010 
I0.WTD, 130,010 
IO0.TDD, 140,010 
IO0.DGN,150,010 
IO.WPD, 160,010 
IO.RPD,170,010 
IO.CER, 200,010 
IO.CEW, 210,010 


MACRO REDEFINITION TO NULL 


UMDIOS A 


$$SGBL 


;ATTEMPT TRANSMISSION 
7;ACCEPT TRANSFER 

; CONNECT FOR RECEPTION 
;DISCONNECT FROM RECEPTION 
;REJECT TRANSFER 


ALL DIAGNOSTIC 


DEFINE THE GENERAL USER-MODE I/O QUALIFIER BIT. 


7USER-MODE DIAGNOSTIC REQUEST 


DEFINE USER-MODE DIAGNOSTIC FUNCTIONS. 


HOME SEEK OR RECALIBRATE 

BLOCK SEEK 

OFFSET POSITION 

READ DISK HEADER 

7 (DISK) WRITE DISK HEADER 

; (DISK) WRITECHECK (NONTRANSFER) 

7; (DECTAPE) READ BLOCK NUMBER FORWARD 

7 (DECTAPE) READ BLOCK NUMBER REVERSE 

7 (MAGTAPE) READ LONGITUDINAL PARITY CHAR 
; (DISK) READ TRACK DESCRIPTOR 

7; (DISK) WRITE TRACK DESCRIPTOR 

7 (DISK) WRITE TRACK DESCRIPTOR DISPLACED 
;DIAGNOSE MICRO PROCESSOR FIRMWARE 

7 (DISK) WRITE PHYSICAL BLOCK 

7 (DISK) READ PHYSICAL BLOCK 

7; (DISK) READ CE BLOCK 

7 (DISK) WRITE CE BLOCK 


7 (DISK) 
7; (DISK) 
7 (DISK) 
7 (DISK) 
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7s 


ze 


Se Ne Ve Ne 


me 


=e we 


~“e 


=e Ne 


- ENDM 


HANDLER ERROR 


Error Codes 


UMDIO$ 


CODES RETURNED IN I/O STATUS BLOCK ARE DEFINED THROUGH THIS 


MACRO, WHICH THEN CONDITIONALLY INVOKES THE MESSAGE-GENERATING MACRO 
FOR THE QIOSYM.MSG FILE 


-MACRO 
DEFINS 
-IF 
-MCALL 
. IOMG. 
- ENDC 
-ENDM 


-IOER. SYM,LO,MSG 
SYM, LO 

GT, $$MSG 

- IOMG. 

SYM, LO, <REFERENCE> (symbol) (MSG) 


- IOER. 


I/O ERROR CODES ARE DEFINED THROUGH THIS MACRO, WHICH THEN INVOKES THE 
ERROR MESSAGE-GENERATING MACRO; ERROR CODES -129 THROUGH -256 
ARE USED IN THE QIOSYM.MSG FILE 


» MACRO 
DEF INS 
IF 
»MCALL 
. IOMG. 
-ENDC 
» ENDM 


CONDITIONALLY 


-MACRO 
» WORD 
- ENABL 
-ASCIZ 
-DSABL 
- EVEN 
-IIF 
~ENDM 


-QIOE. SYM, LO, MSG 
SYM, LO 

GT, $$MSG) 

. IOMG. 

SYM, <LO-128.>, <REFERENCE> (symbol) (MSG) 


. QIOE ° 
GENERATE DATA FOR WRITING A MESSAGE FILE 


- IOMG. SYM, LO, MSG 
-*O<REFERENCE> (symbol) (LO) 
Lc 

“MSG* 

Lc 


LT, “O<REFERENCE> (symbol) ($$$MAX+<REFERENCE> (symbol) (LO) ) , $$$MAX=-“O<REFERED 


- IOMG. 


DEFINE THE SYMBOL SYM WHERE LO IS THE LOW-ORDER BYTE, HI IS THE HIGH BYTE 


» MACRO 
DEFINS 
- ENDM 
-DSABL 


.WORD. SYM,LO,HI 

SYM, <REFERENCE> (symbol) (HI*400+L0) 
.WORD. 

Lc 
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L.2 


IAS FCS Library Options 


FCS Library Options 


During system generation, the system manager has the option of selecting one of several File 
Control Services (FCS) libraries as the default FCS library. You can replace the default library in 
SYSLIB with one of the other libraries shown in Table L—1 by using the /RP switch to the Librarian 
Utility Program (LBR). Refer to the JAS Utilities Manual for more information. Table L—1 contains 
a brief description of the FCS libraries that are available with each IAS system. 


Table L-1 FCS Library Descriptions 


FCS Library Option Description 

[1,1JFCS.OBJ Includes standard FCS routines. Distributed and included in SYSLIB.OLB as the 
default FCS library. 

[1, 1JFCSMTA.OBJ Includes standard FCS routines, plus American National Standards Institute 


(ANSI) magnetic tape support and “big buffering” (see Chapter 2 for block buffer 
size override specification). Distributed and included as the default FCS library 
routines for IAS. 


[1,1]FCSMBF.OBJ Provides multibuffering support, big buffering support, and ANSI magnetic tape 
support in addition to the standard FCS routines. 


-FCTYP 


The FCS routine .FCTYP returns a description of the FCS conditional assembly parameters that 
were set when FCS was built. 


CALL .FCTYP 
There are no input parameters. 
The information is returned in R1. The bits set in the mask word returned in R1 correspond to the 


conditional assembly parameters shown in Table L—2. 


Table L-2. .FCTYP Values 


Conditional 

Assembly Symbol R1 Bit Mask Symbol Meaning 

R$$ANI FT.ANI ANSI magnetic tape support 
R$$BBF FT.BBF Big buffer support 

R$$MBF FT.MBF Multibuffer support 


L-1 


Index 


Access control parameter 
F11ACP *H-8 

Access shared function *2~12 

Access shared read function « 1-12 

Access shared write function * 1-12 

ACP 

error return * H-3 
1E.ABO + H--3 
IE.ALC «H-3 
IE.ALN ¢H-3 
IE.BAD - H-3 
IE.BDR * H--3 
IE.BTP * H-3 
IE.BVR -H-3 
lE.BYT » H-3 
1E.CKS * H-3 
IE.CLO*H-3 
IE.DFU * H-3 
1E.DUP - H--3 
1E.EOF « H-3 
IE.HFU « H-4 
IE.IFC »>H-4 
1E.1FU -H-4 
1E.LCK » H-4 
1E.LUN » H-4 
IE.NOD « H--4 
IE.NSF + H-4 
1E.OFL * H—-4 
1E.PRI*H-4 
IE.RER « H-4 
IE.SNC + H-4 
IE.SPC * H-4 
IE.SQC + H-4 
IE.WAC * H--4 
IE.WAT * H--4 
IE.WE:R * H-4 
IE.WLK * H-4 
QIO$ function 

closing a file * H-2 
creating a file * H—2 
deleting a file * H-3 
extending a file * H-2 
opening a file * H-2 
using « H—2 


ACP (Cont.) 
QIO$ interface » H-1 
Action routine * 7—4 
calling «74 
using * 7-5 
ALUNS$ directive summary « F—1 
Ancillary control processor 
See ACP 
ANSI tape standard * G—1 
Append file open function * 2-12 
.ASCPP routine 
converting UIC to binary * 4—7 
.ASLUN routine 
assigning LUN « 4-8, 4—12 
AST 
service routine * 2-37 
AST service routine * 2-37 
Asynchronous system trap 
See AST 
Attribute buffer 
F11ACP 
address * H—7 
Attribute list 
F11ACP -H-5 
Attribute size » H-7 
Attribute type 
F11ACP -H-6 
tile characteristic » H-6 
fille name * H-6 
file owner * H-6 
file protection > H-6 
file type *H-6 
placement control « H-7 
read file header * H-7 
record I/O area > H-6 
revision number * H—-7 
statistics block * H-6 
version number * H-6 


B 


Binary to ASCII conversion 

UIC + 4-7 
Blank 

ignoring in command line * 7-6 
Block 


Index-1 


index 


Block (Cont.) 
locking * 2—13, 2-37, 2-38 
enable «2-13 
F11ACP *H—-9, H—10 
logical « 5—1 
unlocking * 2-38 
virtual » 5—1 
Block access 
initialization * 2-10 
READ$ macro * 2—10 
WRITE$ macro « 2—10 
Block boundary «2-5 
crossing 
record attribute «3-7 
fixed-length record 
PUT$ macro « 3-23 
FSR block buffer * 3~22 
variable-length record 
PUT$ macro « 3-23 
Block buffer 
initializing FDB «2-14 
pool space 
FSR « 2-31 
Block /O - 2-8 
block size « 2—10 
buffer *2—10 
completion event flag * 2-10 
I/O status block * 2-11 
operation « 1—7 
FD.RWM parameter ¢ 3-5 
request 
record attribute » 3-7 
Block size 
block I/O + 2~10 
override + 3-8 
resetting 
CLOSE$ macro * 2-15 
Block tape 
override size * 2-15 
Buffer 
attribute 
address * H-7 
count 
multiple * 2-15 
multiple » 2-15 
count « 3-8 
type * 2-15 
. pool space 
FSR ¢ 2-31 
specifying number + 2-16 
task record * 3-17 
locate mode * 3-23 


Index—2 


Buffer 
task record (Cont.) 
PUT$ macro + 3-22 
Buffer boundary 
locate mode * 3-18 
Buffer count 
default » 2—16 
Buffer descriptor 
task * 3-8 
Buffer flush routine * 4~22 
Buffer FSR block 
locate mode * 3-18 
space allocation «2-16 
Buffering 
big * 1-11 
multiple 
performance « 1-10 
record I/O + 1—10 


C 


Carriage control «2—5, 2-6 
record attribute * 3-7 
word 
record attribute + 3—7 
CCML$ macro « 6-10 
Checksum value * 5—4 
CLOSE$ 
example of CLOSE$ macro « 5—9 
CLOSE$ example « 5-9 
CLOSE$ macro « 3—1 
file processing * 3—15 
completion * 2—7 
format 
file processing «3-15 
resetting 
block size «2-15 
Command file 
closing « 6—10 
resetting scan macro « 6-9 
Command line 
ignoring blanks and tabs * 7-6 
parsing * 7—1 
processing * 6—1 
Command String Interpreter 
See CSI 
Conversion 
VIC 
ASCil/binary * 4-7 


Conversion (Cont.) 
VIC, ASCli/binary » 4—6 
CSI - 6-1 
initializing control block * 6-15 
parsing file specification * 6-15 
CSI$1 macro 
command syntax analyzer «6-15 
CSI$2 macro 
command semantic parser * 6-16 
initializing control block * 6-15 
parsing file specification «6-15 
CSI$ macro * 6-12 
CSI$ND macro + 6-18 
defining end of descriptor table «6-25 
CSI$SV macro * 6-18 
creating switch value descriptor table entry » 6—23 
CSI$SW macro « 6-18 
creating switch descriptor table entry » 6-18 
CSI control block 
bit values definition * 6-12 
offsets definition *6—12 
CSI macro 
switch definition » 6-18 
CSI routine « 6-11 
CSI runtime macros * 6-15 
.CTRL routine 
control device * 4—21 
tape « 5—7 


D 


Data format 
ANSI tape « 1—7 
file device » 1-6 
Data-set descriptor » 2—23 
address 
initialization «2-12 
as data structure * 1-4 
definition « 1-3 
general description * 1-5 
OFNB$x macro + 3-13 
pointer 
definition * 1-3 
pointer file-open * 2-11 
pointer initialization «2-12 
specifying » 2—22 
Deaccess lock 
Fi1ACP + H-8 
$DEBUG « 7-2 
Debug routine «7-5 


index 


DECtape file structure * 5—1 
Default Filename Block 
See DFNB 
DELET$ macro « 3-1, 3-33 
Device control routine * 4—21 
Device information 
-PRSDV routine + 4—11 
Device name 
string descriptor *2—23 
Device name field » 2-28 
DFNB « 2-25, 3-13 
as data structure « 1—4 
definition * 1-3 
FNBLK$ macro * 2-25 
OFNB$x macro « 3-13 
specifying «2-22 
Directive summary 
/O related * F—1 
Directory 
file »5~—2 
identification information 
-PARSE routine »* 4—9 
-PRSDI routine » 4-12 
structure * 5—2 
Directory entry 
deleting 
-REMOV routine » 4-15 
inserting 
-ENTER routine » 4—14 
locating 
.FIND routine *4—13 
routine * 4-12 
Directory identification 
FNB (F11ACP) » H-9 
Directory string 
default 
read * 4-2 
write * 4—3 
routine 
default » 4—2 
Directory string descriptor * 2-23 
Disk file structure » 5—1 
-DLFNB routine 
deleting file by filename block + 4—21 


E 


End-of-file label 
tape * G-7 


Index-3 


index 


End-of-file READ$ macro « 3-28 
End-of-tape handling » G-8 
End-of-volume label 

tape * G-7 
-ENTER routine 

inserting directory entry * 4-14 
Error code 

block locking «2-39 

file operations * K—1 

shared file «2-39 
Error return 

ACP -H-3 

GCMLD$ macro « 6-5 
Error return IE.IFC *2—40 
Error return IE.LCK * 2-40, 2-41 
Error return IE.ULK « 2-40 
Error return IE.WAC « 2-40 
Error routine 

file macro * 3-1 
Event flag 

1/O coordination + 2-35 

1/0 synchronization » 3-8 
-EXPLG module 

logical name expansion « 4—11 
Extend control parameter 

F11ACP *H-7 
Extension default »2—16 
-EXTND routine 

extending file + 4-19 


F- 


F.ACTL field 

number of retrieval pointers * A—7 
F.ALOC field 

number of blocks allocated for extend » A-5 
F.BBFS field 

block buffer size * A-6 
F.BDB field 

block buffer descriptor block address * A~7 
F.BGBC field 

big-buffer block count * A-6 
F.BKDN field 

AST service routine address * A~5 
F.BKDS field 

block I/O buffer descriptor * A—5 
F.BKEF field 

block I/O event flag * A-6 
F.BKP1 field 


Index—4 


F.BKP1 field (Cont.) 


FCS internal control bits » A—6 
F.BKST field 

/O status block address « A-5 
F.BKVD field 

user virtual block number * A-6 
F.CHR field 

volume characteristics byte « A—7 
F.CNTG field 

number of blocks to be allocated * A-5 
F.DFNB field 

default filename block pointer * A-6 
F.DSPT field 

data-set descriptor pointer *A-6 
F.EFBK field 

end-of-file block number * A—4 
F.EFN field 

record I/O event flag » A-6 
F.EOBB field 

end-of-block buffer » A—5 
F.ERR1 field 

F.ERR extension * A-6 
F.ERR field 

error return code byte * A-6 
F.EXT field 

FDB extension address » A—7 
F.FACC field 

file access byte * A-6 
F.FFBK field 

first free byte in last block * A-4 
F.FLG field 

flag byte * A—7 
F.FNB field 

filename block offset * A—7 
F.HIBK field 

highest allocated virtual block number * A-4 
F.LUN field 

FDB + 4—12 

LUN for FDB «- A-5 
F.MBC1 field 

number of buffers in use * A-6 
F.MBCT field 

number of multiple buffers * A-6 
F.MBFG field 

multibuffer flag word * A—6. 
F.NRBD field 

next record buffer descriptor * A—5 
F.NREC field 

address of next record in block » A—5 
F.OVBS field 

override block buffer size * A~5 
F.RACC field 


F.RACC field (Cont.) 

record access byte * A—4 
F.RATT field 

record attribute byte * A-4 
F.RCNM field 


random access record number « A—5 


F.RCTL 
device characteristic byte 
-PARSE routine * 4—9 
F.RCTL field 
device characteristics byte «A-5 
F.RSIZ field 
record-size word » A—4 
F.RTYP field 
record-type byte *A—4 
F.SEQN field 
sequence number « A—7 
F.STBK field 
statistics block address * A—5 
F.URBD field 
user record buffer descriptor « A-5 
F.VBN field 
virtual block number ¢ A—7 
F.VBSZ 
device buffer size word 
-PARSE routine * 4-9 
F.VBSZ field 
device buffer size word * A-6 
FA.DLK value 
not lock file » 2-13 
FA.EXL value 
block locking * 2--13 
FA.LKL value 
block locking * 2-13 
FA.NSP value 
opening file no superseding »* 3—-14 
FA.POS value 
file position on close » 2-13 
FA.RWD value 
rewinding on close or open * 2-13 
FA.SHR value 
opening file shared access * 3-14 
FA.TMP value 
opening temporary file «3-14 
FCS + 1-1 
data structure 
general + 14 
file access method « 1-5 
/O macro * 2-1 
important characteristic « 1-3 
library options * L-1 


index 


FCS (Cont.) 
library symbols « |-1 
macro 
FDB information »* 2—1 
-MCALL directive + 2-2 
term definitions « 1—1 
with task builder + 1—1 
FCS.OBJ FCS library * L~1 
FCS impure area «2-31 
FCSMBF.OBJ FCS library « L—1 
FCSMTA.OB4J FCS library * L—1 
FCSRES routines « 1—17 
.FCTYP routine 
assembly parameters ¢L—1 
FD.BLK parameter 
record attribute » 2-5 
block boundary crossing * 3—7 
FD.CR parameter 
record attribute » 2-5 
line-feed character * 3—7 
FD.FTN parameter * 3—7 
FD.INS parameter 
sequential file » 2-9 
sequential mode + 3-5, 3-8 
FD.PLC parameter 
locate mode * 2-9, 3-5 
move mode «2-9 
FD.PLC parameter locate mode « 3-8 
FD.PRN parameter 
record attribute * 2-5 
FD.PRN parameter record attribute carriage-control 
word * 3-7 
FD.RAH parameter 
read-ahead operation + 3-9 
FD.RAH value 
read-ahead * 2—15 
FD.RAN parameter 
random access ¢ 2-8, 3-8 
random record I/O « 3-5 
FD.RTN 
record attribute * 2-5 
FD.RWM parameter 
block I/O operation * 3-5 
record access * 2-8 
record attribute process with block I/O * 3-7 
FD.WBH parameter 
write-behind operation + 3-9 
FD.WBH value, write behind « 2-16 
FDAT$A macro «2-4 
FDAT$R macro * 2-17 
FDB + 2-3 
address 
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Index 


FDB 


address (Cont.) 


run-time macro * 2-19 
allocating file block » 2-6 
as data structure « 1—4 
block I/O * 2-8 
block locking * 2-13 
block size 

resetting * 2-15 
carriage control * 2-6 
definition * 1-2 
description « 1-4 
extension 

logical name translation + 4—11 
F.LUN field * 4-12 
F.xxxx field * A—4 
file identification + 3-8 
GET$ macro * 3-17 
initialization * 2-3 
initializing block access * 2-17 
initializing block buffer *2—14, 2-17 
initializing block buffer size «2-14 
initializing file attribute » 2-4, 2-17 
initializing file-open section * 2-11, 2-17 
initializing record access * 2-8, 2-17 
initial values * 2—1 
largest record size * 2-6 
LUN specification + 3-8 
macro global symbol + 2-21 
macro local symbol « 2-21 
macro run-time exceptions * 2-17 
macro run-time initialization * 2-17 
multi-buffering «2-15 
multi-buffering type * 2-15 
offset 

global/local * 2-20 
OPEN$x macro requirement * 3-6 
PUT$ macro operation * 3-22 
record I/O * 2-8 
record size * 3-7 
sequence number field « 2-6 
space allocation *2—4 
WRITES$ macro « 3-31 


FDBDF$ macro 


FDB space allocation »2—4 


FDBF$A macro « 2-14 


example of FDBF$A macro 2-16 


FDBF$R macro « 2—17 
FDBK$A 


example of FDBK$A macro « 2-11 


FDBK$A macro 


block access initialization «2-10 
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FDBK$A macro (Cont.) 


record access 
block I/O * 2-10 
FDBK$R macro 
initializing block access * 2-17 
FDOP$A macro « 2-11 
example of FDOP$A macro «2-14 
FDOP$R macro, initialize file-open section * 2-17 
FDRC$A macro * 2-8 
example of FDRC$A macro * 2-8 
FDRC$R macro 
initializing record access * 2-17 
File 
access method 
FCS «1-5 
attribute size (F11ACP) * H-7 
closing » 3-15 
current command « 6-10 
indirect command * 6-9 
temporary * 3-10 
creating 
FO.WRT value « 3-14 
temporary * 3-10 
temporary mark for deletion » 3-11 
delete routine » 4-21 
deleting * 3-33 
deleting routine * 4-21 
device 
data format + 1-6 
directory * 5-2 
extending, routine »* 4-19 
extending WRITE$ macro « 3-30 
extension 
default «2-16 
default size + 2—7 
size * 2-7 
virtual block » 2-7 
/O coordination * 2-34 
/O status block * 2-36 
identification in FNB (F11ACP) *H-9 
index * 5-2 
intializing 
record access * 2-17 
locking * 2-13 
marking 
for deletion + 3-11 
name block 
See FNB 
name block pointer «* H—9 
name in FNB (F11ACP) * H-9 
no locking on close * 2-13 


File (Cont.) 
opening 
append « 2-12 
by filename block * 3-12 
by ID » 3—11 
for append FO.APD value + 3—14 
for file access «3-14 
for modify * 3-14 
for read «3-14 
for shared access FA.SHR value * 3-14 
for update and extend « 3-14 
for write FO.WRT value + 3-14 
lock on close + 2-13 
modify *2—12 
no supersede ¢ 2-12, 3-14 
on LP for printing * 8—2 
processing ¢ 3-3 
read access * 2-12 
shared access * 2-12 
tape position «2-13 
temporary * 2-12, 3-10 
temporary FA.TMP value * 3-14 
temporary mark for deletion » 3—11 
update «2-12 
write access * 2-12 
opening by ID * 2-28 
operation 
multiple » 5-6 
single « 5-6 
position 
by byte «2-9 
on closing * 2-13 
random I/O + 2-16 
renaming « 4-19 
sequenced * 2—5 
reading *2—6 
writing * 2-6 
sequence number ¢ 2-6 
shared access ¢ 1-12 
space preallocation «2-16 
specification 
definition * 1-3 
specifying 
within program ¢ 2-22 
truncating routine » 4-20 
truncation * 2-9 
type FNB (F11ACP) * H-9 
version number in FNB (F11ACP) * H—-9 
window pointer number « 2-13 
File access 
optimizing * 2-28 
File attribute 


Index 


File attribute (Cont.) 
initializing 2-4 
initializing run-time * 2-17 
File block 
access initialization * 2-10 
access initializing run-time * 2-17 
allocation * 2-6 
buffer initialization * 2-14 
run time * 2-17 
locking «2-13 
File characteristic 
system-controlled characteristic 
SC.BAD + C-3 
system-controlled characteristis 
SC.MDL « C-3 
user-controlled 
UC.CON 
contiguous file »C~3 
UC.DLK 
file improperly closed » C-3 
File control routine * 4—1 
File Control Services 
See FCS 
File Descriptor Block 


See FDB 
File header block * 5—3 

format * C—1 

H.XXXX field « C—1 

header area 
file characteristics » C—3 
file owner information « C-3 
file protection code * C—3 

1.XXXX field »C—1, C-2 

identification area » C-3 
creation date » C—4 
creation time » C—4 
expiration date » C—4 
filename * C-3 
filetype * C—-3 
file version number * C—3 
revision date » C—3 
revision number * C—3 
revision time » C-3 

M.XXXX field * C—2 

map area» C-4 

tape -G-8 

File header label 

ANSI - 5—5 

tape *G-3 
HDA1 - G-3 
HDR2 - G4 
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index 


File header label 
tape (Cont.) 
HDR3 - G4 
File identification « 5-3 
FDB «3-8 
field «2-28 
File Identification Block 
F11ACP *H-5 
File identifier processing 
by Files-11 
tape * G-6 
File label 
tape » G-1 
File macro « 3—1 
access privileges « 3-3 
error routine > 3-1 
File name 
-PARSE routine * 4—10 
.PRSEN routine * 4—12 


tape 


Radix-50 conversion * 4—14 


Filename block 
See also FNB 
default * 2—25, 3-13 
initialization *2—12 
default directory information 
.GTDID routine » 4—16 
default file-open * 2—11 
default OFNB$x macro * 3-13 
deleting file » 4-21 
directory information 
-GTDIR routine » 4—15 
initializing * 2-28 
manually ¢ 2-30 
local offset definition * 2-27 
N.DID field 
.PARSE routine + 4-9 
N.DVNM field * 4—12 
N.NEXT word 
.PARSE routine * 4—11 
N.STAT word 
-PARSE routine « 4—11 
NBOF$L macro ¢ 2—27 
NMBLK$ macro « 2—25 
OPENS$x macro « 2-28 
opening 
file by » 3-12 
-PARSE routine 
disk * 4-7 
N.DID field » 4-9 
N.FID field » 4-9 
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Filename block 
-PARSE routine (Cont.) 
tape 4-8 
routine * 4-7, 4-15 
specifying 
default * 2-22 
Filename string descriptor * 2-24 
File number « 5-3 
File operation 
error codes * K—1 
File owner word « 4—5 
reading ° 4-6 
writing * 4-6 
File pointer routine * 4-16 
File position 
save «4-18 
to byte 
.POINT routine « 4-16 
to record 
-POSRC routine * 4—17 
File processing 


completion CLOSE$ macro « 2—7 


File protection word * 4—4, 4—5 


File read-ahead FD.RAH parameter * 3-9 


File record 
attribute + 2-5 
File rename routine * 4-19 
FILES-11 structure * 5~—1 
File sequence number « 5-3 
File specification 
device « 1-13 
magnetic tape « 1-15 
-PRSDV routine * 4—11 
directory * 1-13 
magnetic tape « 1-16 
-PRSDI routine *4—12 
dynamic processing 
SYSLIB «2-28 
generation « 1-16 
magnetic tape * 1-15 
name «1-14 
quoted string 
magnetic tape « 1-16 
syntax description * 1-13 
type «1-14 
unit 
.PRSDV routine «4-11 
version « 1-15 
magnetic tape « 1-16 
File Storage Region 
See FSR 


File structure » 5—1 

tape «G—7 

user ¢ 5—1 

virtual blocks » 5—1 
File trailer label 

tape *G-7 
File type 

-PARSE routine » 4—10 

-PRSEN routine * 4-12 
File version 

-PARSE routine * 4-10 

-PRSEN routine * 4—12 
-FIND routine 

locating directory entry °4—13 
FINIT$ macro 

FSR initialization run-time »* 2-32 
-FINIT routine 

initializing before .PARSE routine + 4-8 
Fixed-length record 

PUT$ macro block buffer » 3-23 


Fixed-length record PUT$ macro block boundary ° 
3-23 


Flush buffer routine + 4—22 
.FLUSH routine . 
flushing buffer » 4—22 
FNB 
definition * 1-2 
F11ACP -H-9 
directory identification * H-9 
file identification * H-9 
file name * H-9 
file type * H—9 
file version number * H-9 
pointer * H-9 
status word * H-9 
wildcard context » H-9 
N.XXXX field « B-2 
FO.APD value 
opening file for appending + 3-14 
FO.MFY value 
opening file for modifying * 3-14 
FO.RD value, open file for read * 3-14 
FO.UPD value 
opening file for updating and extending * 3-14 
FO.WRT value open file for write and create « 3-14 
FORTRAN carriage-control 
record attribute » 3—7 
FSR 
as data structure + 1-4 
block buffer 
block boundary * 3-22 
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FSR 
block buffer (Cont.) 
locate mode * 3-18, 3-23 
pool space « 2-31 
space allocation » 2-16 
definition * 1-3 
general description « 1-5 
increasing size 
FORTRAN ¢ 2-34 
MACRO-11 * 2-33 
initalization FINIT$ macro * 2-32 
initialization FSRSZ$ macro ° 2-31 
initializing * 2-30 
record I/O «2-31 
record I/O multibuffering * 2-31 
$$FSR1 + 1-5 
$$FSR2 program section 
default UIC «4-4 
file owner word ¢ 4-5 
file protection word « 4—4 
general description * 1-5 
FSRSZ$ macro 
FSR initialization * 2-31 


G 


GCML « 6-1 
control block 
allocating * 6-2 
defining bit values - 6-5 
defining offsets * 6-5 
initializing * 6-2 
routine 
runtime error * 6—7 
use * 6-11 
GCML$ macro « 6-7 
GCMLB$ macro « 6-2 
GCMLD$ macro « 6-5 
GET$ macro « 1-8, 3-1 
example of GET$ macro « 3-17 
FD.RWM parameter 
record I/O * 2-8 
FDB . 
file processing * 3-17 
file processing «3-15 
locate mode * 3-18 
move mode « 3-18 
format 
file processing * 3-16 
GETS$R macro « 3—1 
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Index 


GET$R macro (Cont.) 


file processing 
read logical record random mode « 3-19 
GET$S macro «3-1 
file processing 
read logical record sequential mode * 3-20 
Get command line macro 
See GCML 
Global symbol 
FDB macro « 2-21 
GLUNS$ directive summary ¢ F--1 
GMCRS$ directive summary « F—1 
-GTDID routine » 4—15 
default directory information ¢« 4-16 
-GTDIR routine * 4—15 
inserting directory information * 4—15 


H 


H.CKSM offset 
checksum word « C~2 
H.FLEV offset 
structure level « C—1 
H.FNUM offset 
file number « C—1 
H.FOWN offset 
offset to file owner « C—1 
H.FPRO offset 
file protection code « C—1 
H.FSEQ offset 
file sequence number + C—1 
H.IDOF offset 
header area * C—1 
H.MPOF offset 
map area offset « C—1 
H.PROG offset 
member number + C—1 
H.PROJ offset 
group number « C—1 
H.SCHA offset 
system-controlled file characteristics » C—1 
H.UCHA offset 
user-controlled file characteristics » C—1 
H.UFAT offset 
user file attributes » C—1 
Header area « 5-3 
file header block + C—2 
file characteristics » C-3 
file number « C—2 
file owner information * C—3 
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Header area 
file header block (Cont.) 
file protection code * C-3 
file sequence number * C—2 
identification area * C—2 
map area offset * C—2 
structure level » C—3 
user file attributes 
file characteristics * C—3 
Header block 
file -5~—3 


|.CRDT offset 
creation date * C—1 
I.CRTI offset 
creation time » C~1 
|.EXDT offset 
expiration date * C—1 
|.FNAM offset 
identification area * C—1 
L.FTYP offset 
file type * C—1 
|.FVER offset 
file version number * C—1 
|.RVDT offset 
revision date * C—1 
|.RVNO offset 
revision number « C—1 
LRVTI offset 
revision time » C—1 
VO 
block operation ¢ 1-7 
data-transfer mode * 1-8 
directive summary « F—1 
function support 
F11ACP *H—1 
MTAACP « H—1 
locate mode * 1-9 
move mode « 1-8, 1-9 
preparation 
FCS macro * 2-1 
record 
big buffering « 1-11 
multibuffering * 1~10 
record operation « 1-8 
synchronization « 1-8 
/O coordination 
event flag * 2-35 


1/0 coordination (Cont.) 
file operation * 2-34 
1/O function 
summary 
F11ACP + H-10 
MTAACP «° H—12 
1/O macro 
AST service routine * 2-37 
FCS «2-1 
FDB + 2-1 


‘ /O macro AST service routine * 2—37 


I/O program example « J—1 
/O status block 
block I/O » 2-11 
defined in task » 2-36 
file /O * 2-36 
/O synchronization event flag * 2-14, 3-8 
1/0 wait for completion block I/O « 3-31 
Identification area » 5-3 
file header block » C-3 
creation date * C4 
creation time * C—4 
expiration date » C4 
filename « C-—3 
filetype * C--3 
file version number * C—3 
revision date * C-3 
revision number « C-3 
revision time * C-3 
IE.ABO error return 
ACP -H-3 
1E.ALC error return 
ACP -H-3 
1E.ALN error return 
ACP -H-3 
1E.BAD error return 
ACP -H-3 
1E.BDR error return 
ACP -H-3 
1E.BTP error return 
ACP -H-3 
1E.BVR error return 
ACP -H-3 
1E.BYT error return 
ACP *H-3 
IE.CKS error return 
ACP -H-3 
1E.CLO error return 
ACP -H-3 
IE.DFU error return 
ACP -H-3 
1E.DUP error return 


1E.DUP error return (Cont.) 


ACP -H-3 
1E.EOF error return 
ACP -H-3 
IE.HFU error return 
ACP +H—4 
1E.IFC error return 
ACP *H-4 
IE.IFU error return 
ACP + H-4 
IE.LCK error return 
ACP -H-4 
IE.LUN error return 
ACP -H-4 
IE.NOD error return 
ACP -H-4 
IE.NSF error return 
ACP -H—4 
1E.OFL error return 
ACP -H—-4 
iE.PRI error return 
ACP *-H—4 
IE.RER error return 
ACP -H-4 
IE.SNC error return 
ACP -H-4 
IE.SPC error return 
ACP -H-4 
1E.SQC error return 
ACP -H-4 
IE.WAC error return 
ACP -H-4 
IE.WAT error return 
ACP -H-4 
1E.WER error return 
ACP *H-4 
IE.WLK error return 
ACP *H-4 
Index file * 5-2 
format * E-1 
IO.ACE function 
F11ACP + H-11 
MTAACP « H-12 
10.ACP function 
MTAACP « H—-13 
10.ACR function 
F11ACP ¢H—-11 
MTAACP + H-12 
1IO.ACW function 
FI1ACP + H—-11 
MTAACP ¢ H—12 
10.APV function 


index 
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index 


10.APV function (Cont.) 


MTAACP ° H-14 
10.CRE function 
F11ACP ¢H~-10 
MTAACP « H-12 
10.DAC function 
F11ACP + H—-11 
MTAACP * H-12 
10.DEL function 
FI1TACP *H-10 
1O.ENA function 
F11ACP *H—11 
MTAACP ¢ H--12 
10.EXT function F11ACP - H—-11 
10.FNA function 
F11ACP *H—11 
MTAACP ¢ H-12 
10.RAT function 
F11ACP *H-11 
MTAACP « H-13 
10.RNA function 
FI1ACP «H-11 
10.RVB function 
F11ACP *H—11 
MTAACP + H-12 
10.ULK function 
F11ACP *H-11 
1IO.WVB function 
F11ACP + H—11 
ISTAT$ macro + 7—1 


K 


Keyword recognition 
transition table * 7-7 


L 


Line-feed character 
record attribute * 3-7 
Local symbol 
FDB macro « 2-21 
Locate mode « 1-9, 2-9 
file processing * 3-23 
FSR block buffer + 3-23 
GET$ macro « 3-16, 3-18 
PUT$ macro « 3-20, 3--23 
record attribute * 3-8 
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Locate mode (Cont.) 
task record buffer * 3-23 
Logical block * 5—1 
file device * 1—7 
Logical name 
translation 
FDB extension « 4—11 
name expansion 
-EXPLG module * 4—11 
-PARSE routine 
device and unit *4—8 
-PRSDV routine « 4—11 
Logical unit number 
See LUN 
LUN 
assigning with AASLUN routine * 4-12 


M 


M.CTSZ offset 

retrieval pointer block count field size » C—2 
M.EFNU offset 

extension file number » C—2 
M.EFSQ offset 

extension file sequence number « C—2 
M.ERVN offset 

extension relative volume number * C—2 
M:ESOQN offset 

map area * C—2 
M.LBSZ offset 

retrieval pointer logical block number field size ¢ 

C-2 

M.MAX offset 

available retrieval pointer words * C-2 
M.RTRV offset 

retrieval pointer start * C—2 
M.USE offset 

retrieval pointer word count « C—2 
Macro global symbol « 2-21 
Macro local symbol « 2-21 
Macro run time 

exceptions * 2-17 

FDB address * 2—19 

initialization *2—17 
Map area « 5-3 

file header block » C4 
.MARK routine 

save file position * 4-18 
Master File Directory 


See MFD 


-MCALL directive » 2-2 
MFD + 5-2 
Move mode » 1-8, 1-9 

GET$ macro « 3--15, 3-18 

PUT$ macro ¢ 3-20, 3-22 
-MRKDL routine 

_marking temporary file for deletion » 4—21 

Mutifile operation * 5-6 


TS PT RT (Se NEP OS ED FRE 
N.ANM1 field 

ANSI filename string « B-3 
N.ANM2 field 

remainder of ANSI filename string « B—4 
N.DID field 

directory identification » B—2 

.PARSE routine * 4-9 
N.DVNM field » 4—12 

ASCIl device name * B—2 

ASCII tape device name * B-4 
N.FID field 

file identification « B—-2, B~3 

-FIND routine * 4—13 

-PARSE routine * 4—9 
N.FNAM field, file name »- B—-2 
N.FTYP field 

file type + B-2 
N.FVER field 

file version number * B—2 

tape file version number ¢ B-3 
N.NEXT field 

context for next .FIND » B—2 

tape context for next .FIND -B—4 
N.STAT field 

filename block status word « B—2 

tape filename block status word * B-3 
N.UNIT field 

FNB (tape) - B—4 

unit number field » B—2 
NBOF$L macro * 2-27 
NMBLK$ macro 

default filename block * 2—25 

example of NMBLK§$ macro * 2-26 
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OFID$ macro « 3~1 


index 


OFID$x macro 
file processing * 3-11 
OFNB§$ macro « 3-1 
OFNB$x macro 
data-set descriptor * 3-13 
default filename block * 3-13 
file processing * 3-12 
OPEN$ macro « 3—1 
example of OPEN$ macro « 5-9 
file processing * 3-14 
OPENS$R macro 
example of OPEN$R macro « 5-8 
OPENS$R macro, shared access * 1~12 
OPEN$x macro 
file processing * 3-2, 3-6 
format 
file operations + 3—4 
Open file processing * 3-3 
Open file routine 
by filename block «3-12 
by ID + 3-11 
existing * 3-7 
for access * 3-14 
for modify » 3-14 
for read * 3-14 
for update and extend * 3-14 
new ° 3-7 
no supersede ¢ 3—14 
OPNS$ macro « 3—1 
OPNS$R macro 
shared access ¢ 1-12 
OPNS$x macro 
file processing «3-9 
OPNTS$D macro « 3-11 
OPNT$ macro « 3-1 
OPNT$W macro 
file processing * 3-10 
Owner ID field tape * G-2 


p 


-PARSE routine 

device and unit translation » 4-8 

logical name translation * 4—7 
Parser program 

TPARS « 7—10 

processing steps ° 7-11 

Placement control F11ACP *H—-9 
.POINT routine 
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Index 


-POINT routine (Cont.) 
file byte position «2-9 
positioning file to byte * 4—16 
.POSIT routine 
returning record position * 4—18 
-POSRC routine 
positioning file to record * 4-17 
-PPASC routine 
converting UIC to ASCII + 4—7 
PRINT$ macro * 8—1 
error handling * 8-2 
PRINT command « 8-2 
Print function 
opening file on LP «8-2 
-PRINT routine 
error handling * 8-2 
-PRINT subroutine + 8—1 
Program example I/O + J—1 
Program section 
TPARS ¢ 7-8 
-PRSDI routine 
filling in directory information + 4—12 
-PRSDV routine 
filling in device/unit information + 4—11 
-PRSFN routine 
filling in file name, type, version * 4-12 
PUT$ macro « 1~8, 3-1, 3-22 
FD.RWM parameter 
record /O «2-8 
FDB 
file processing » 3-22 
file processing 
locate mode * 3-23 
write logical record * 3-20 
file truncate » 2-9 
fixed-length record » 3-22 
block boundary * 3~23 
block buffer « 3-23 
locate mode * 3-20, 3-23 
move mode « 3-20, 3-22 
no truncate function «2-9 
sequenced record * 3-20 
task record buffer * 3-22 
variable-length record * 3—22 
block boundary * 3-23 
PUT$R macro « 3-1 
example of PUT$R macro « 3-25 
file processing 
write logical record random mode + 3-24 
random mode 
locate mode execution » 3-25 
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PUT$S macro « 3-1 
PUT$S macro file processing write logical record, 
sequential mode + 3-25 


Q 


QIO$ 
ACP interface * H—1 
parameter list (F11ACP) »*H—5 
QIO$ directive summary » F—1 
QIO$ function 
ACP 
closing a file * H-2 
creating a file «H-2 
deleting a file * H-3 
extending a file * H-2 
opening a file *H-2 
using * H-2 
QIO execution routine * 4—18 
QIOWS$ directive summary * F~2 


R 


R.FIX 
file attribute »2—5 
parameter 
fixed-length records * 3-7 
R.SEQ 
file attribute » 2-5 
parameter 
sequenced records ¢ 3-7 
R.VAR 
file attribute * 2-5 
parameter 
variable-length records * 3—7 
Random access « 2-8 
Random access mode «3-17 
record attribute » 3-8 
Random I/O * 2-16 
Random mode 
PUT$R macro 
locating mode execution * 3-25 
writing logical record * 3-24 
RCML$ macro « 6-9 
RCST$ directive summary ¢ F—2 
RCVD$ directive summary * F-2 
RCVX$ directive summary * F—2 
-RDFDR routine 


-RDFDR routine (Cont.} 


reading $$FSR2 default directory string « 4—2 
-RDFPP routine 
reading $$FSR2 default file protection word * 4—5 
-RDFUI routine 
reading default UIC » 4-3, 4-4 
Read $$FSR2 
default directory string «4-2 
READ$ macro « 1-8, 3—1 
block access * 2--10 
end-of-file » 3-28 
example of READ$ macro * 3-27 
FD.RWM parameter 
block 1/0 « 2-8 
FDB 
file operation » 3-28 
file processing 
reading virtual block * 3-25 
format file processing * 3-26 
virtual block number + 3-26 
Read access function 
F11ACP + H-10 
file open * 2-12 
shared ¢ 1-12 
Read-ahead file processing * 2-15 
Read function 
default UIC + 4-4 
file protection word 
default » 4-5 
logical record file processing * 3-15 
logical record random mode file processing » 3-19 
logical record sequential mode * 3-20 
virtual block file processing * 3-25 
Record 
fixed-length 
R.FIX parameter * 3-7 
sequenced 
R.SEQ parameter ¢ 3-7 
variable-length * 1~6 
R.VAR parameter * 3-7 
Record access initialization * 2-8 
Record attribute «2-5, 3-7 
FD.BLK parameter 
block boundary crossing * 3-7 
FD.CR parameter * 2-5 
line-feed character * 3—7 
FD.FTN parameter * 2-5 
FORTRAN carriage-control » 3-7 
FD.RAN parameter 
randorn access mode « 3-8 
FD.RPN parameter 
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Record atiribute 
FD.RPN parameter (Cont.) 
carriage-control word « 3—7 
locate mode « 3-8 
sequential mode « 3-8 
FD.RWM parameter 
process with block I/O + 3-7 
Record buffer task 
locate mode * 3-23 
Record fixed-length PUT$ macro » 3-22 
Record format 
tape -5—4 
Record I/O * 2-8 
FSR ¢ 2-31 
FSRZ 
multi-buffering * 2—31 
locate mode 
FD.PLC parameter ¢ 3-5 
macro calls «2-8 
mode « 1-8 
multibuffering » 1-10 
operation ° 1-8 
random 
FD.RAN parameter ¢ 3-5 
synchronization, event flag «2-14 
Record sequenced PUT$ macro « 3-20 
Record size 
FDB « 3-7 
fixed-length * 2-6 
largest * 2-6 
Record variable-length PUT$ macro « 3-22 
-REMOVE routine 
deleting directory entry * 4-15 
.RENAME routine 
renaming file *4—19 
.RFOWN routine 
reading $$FSR2 file owner word * 4-6 
$RONLY macro 
state table * 7-2 
Run-time initialization 
FSR FINIT$ macro * 2-32 


S 


S.HDHD offset 

header area size * C—1 
S.IDHD 

identification area size * C-2 
S.MPHD offset 

map area size » C—2 
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SC.MDL 
bad data block 
user-controlled file characteristic « C—-3 
file marked for deletion 
user-controlled file characteristic » C-3 
Security information DELET$ macro * 3-33 
Sequenced mode GET$ operation * 3-16 
Sequential file * 2-9 
Sequential mode 
FD.INS parameter * 3—5 
record attribute * 3—8 
write logical record « 3-25 
Shared access 
file open * 2-12, 3-9 
Shared access file * 1-12 
Single file operation » 5-6 
Size parameter 
F11ACP -H-7 
Special character state table » 7—7 
Spooling ¢ 8—1 
-PRINT subroutine « 8—1 
STATE$ macro «7-1, 7-2 
$STATE program section + 7-2 
State table * 7-1 
arrangement of syntax types * 7-6 
initializing » 7-1 
rejecting transitions * 7-17 
special character * 7—7 
using subexpressions ¢ 7—17 
Statistics block « D—1 
address « 3-9 
Status word 
F11ACP 
FNB * H-9 
Subexpression, parsing complex command lines « 
7-17 
Syntax element 
defining * 7—2 
Syntax state table «7-6 


T 


Tab 

ignoring in command line * 7-6 
Table Driven Parse 

See TPARS 
Tape 

ANSI file structure » 5—1 

data format + 1—7 

end-of-file label » G—7 
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Tape (Cont.) 
end-of-volume label * G—7 
file header block » G-8 
file processing * 5—4 
tile structure « G—7 
fixed-length records * 1—7 
handling end-of-tape * G-8 
owner ID field - G—2 
position to next file »5—5 
processing example * 5—7 
record format * 5—4 
user file label » G—7 
user volume label *« G-3 
variable-length record * 1-7 
volume access ¢ 5-5 
volume label » G—1 
Tape file 
header label « G—3 
HDR1 * G-3 
HDR2 * G-4 
HDR3 « G4 
identifier processing « G-6 
label * G—1 
Tape position 
file opens 2-13 
Tape read function 
indirect command file * G—8 
Tape standard 
ANSI - G—1 
Task 
spooling print job * 8—1 
Task buffer descriptor « 3-8 
Task record buffer * 3—17 
TPARS 
built-in variable « 7—4 
coding * 7-1, 7-6 
command line parsing * 7-1 
creating parser program * 7-10 
invoking * 7—9 
macro * 7—1 
options word * 7-10 
programming examples « 7—11 
program section * 7-8 
register usage * 7-10 
state table * 7-1 
subexpression * 7-5 
transition * 7-1 
TRAN$ macro * 7-1, 7-2 
Transition table 
recognition of keyword * 7—7 
-TRNCL routine 


.TRNCL routine (Cont.) 
truncating file » 4--20 


U 


UC.CON 
contiguous file 
user-controlled file characteristic « C—3 
UC.DLK 
file improperly closed 
user-controlled file characteristic > C-3 
UFD + 5-2 
UIC + 5-2 
ASCll-binary conversion « 4—6, 4—7 
read/write defaults * 4-3, 4—4 
Unit information 
.PRSDV routine » 4—11 
Unit number field « 2—28 
User file attributes 
header area 
file characteristics « C—3 
User File Directory 


See UFD 
User file label 
tape * G—7 
User Identification Code 
See VIC 
User volume label tape * G-3 
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Variable-length record block boundary PUT$ macro + 
3-23 

Virtual block 

file device » 1-7 

file extension * 2--7 
Virtual block number 

READ$ macro « 3-26 

WRITE$ macro + 3-29 
Volume default extend size + 2—7 
Volume label 

tape * G-1 
Volume label tape user » G-3 
Volume sets 

rewinding « 5-5 
VRCD$ directive summary + F—3 
VRCS$§ directive summary « F—3 
VRCX$ directive summary ° F-3 


index 


VSDA$ directive summary « F—4 
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WAIT$ macro 
file processing ¢ 3—1 
block I/O completion * 3—31 
format file operations * 3-31 
with READ$ and WRITE$ « 3-31 
with READ$ or WRITE$ + 3-26 
.WDFPP routine 
writing $$FSR2 default file protection word * 4-5 
.WDFR routine 
writing $$FSR2 default directory string « 4—3 
.WDFUI routine 
writing default UIC + 4-3, 4—4 
.WFOWN routine, write $$FSR2 file owner word * 4-6 
Wildcard 
context (F11ACP) 
FNB * H-9 
file name * 4-14 
file type «4-14 
Window pointer number * 2—13 
Window size parameter 
F11ACP -H-8 
Write $$FSR2 macro 
default directory string * 4—3 
WRITE$ macro « 1-8, 3—1 
block access * 2—10 
example of WRITES macro « 3-30 
extending file * 3-30 
FD.RWM parameter 
block I/O * 2-8 
FDB + 3-31 
file processing * 3-28 
writing virtual block « 3-28 
format * 3-29 
virtual block number * 3-29 
Write access 
F11ACP *H-10 
file open «2-12 
shared « 1-12 
Write-behind file processing * 2-16 
Write-behind operation 
FD.WBH parameter * 3-9 
Write default UIC function » 4—4 
Write file protection word function 
default * 4—5 
Write function 
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Write function (Cont.) 
file owner word « 4-6 
Write logical record function 
file processing « 3-20 
random mode « 3-24 
sequential mode « 3-25 
Write virtual block file processing « 3-28 
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.XQIO routine 
executing QIO «4-18 
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